Java example source code file (Javadoc.gmk)

This example Java source code file (Javadoc.gmk) is included in the alvinalexander.com "Java Source Code Warehouse" project. The intent of this project is to help you "Learn Java by Example" ^TM.

Learn more about this Java project at its project page.

Java - Java tags/keywords

all_other_targets, api, common_javadocflags, create, directory_cache, draft_header, echo, get2docsdir, java, javadocsummary, optiononly, the

The Javadoc.gmk Java example source code

# Copyright (c) 1997, 2013, Oracle and/or its affiliates. All rights reserved.
# DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
#
# This code is free software; you can redistribute it and/or modify it
# under the terms of the GNU General Public License version 2 only, as
# published by the Free Software Foundation.  Oracle designates this
# particular file as subject to the "Classpath" exception as provided
# by Oracle in the LICENSE file that accompanied this code.
#
# This code is distributed in the hope that it will be useful, but WITHOUT
# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
# FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
# version 2 for more details (a copy is included in the LICENSE file that
# accompanied this code).
#
# You should have received a copy of the GNU General Public License version
# 2 along with this work; if not, write to the Free Software Foundation,
# Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
#
# Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
# or visit www.oracle.com if you need additional information or have any
# questions.
#

include $(SPEC)
include MakeBase.gmk

.SUFFIXES: # Delete the default suffixes
.SUFFIXES: .java

#
# Definitions for $(DOCSDIR), $(MKDIR), $(BINDIR), etc.
#

DOCSDIR=$(OUTPUT_ROOT)/docs
TEMPDIR=$(OUTPUT_ROOT)/docstemp

JDK_SHARE_SRC=$(JDK_TOPDIR)/src/share
JDK_SHARE_CLASSES=$(JDK_SHARE_SRC)/classes

JDK_IMPSRC = $(JDK_OUTPUTDIR)/impsrc

JDK_GENSRC = $(JDK_OUTPUTDIR)/gensrc

HOTSPOT_DOCS_IMPORT_PATH=$(HOTSPOT_OUTPUTDIR)/docs

BUILD_NUMBER=$(JDK_BUILD_NUMBER)

JAVADOC_CMD = $(JAVA) \
    -Xmx1024m \
    -Djava.awt.headless=true \
    $(NEW_JAVADOC) \
    -bootclasspath $(JDK_OUTPUTDIR)/classes

# Copyright year for beginning of Java and some of the apis
# (Needed when creating the javadocs)
FIRST_COPYRIGHT_YEAR = 1993
DOMAPI_FIRST_COPYRIGHT_YEAR = 2005
MIRROR_FIRST_COPYRIGHT_YEAR = 2004
DOCLETAPI_FIRST_COPYRIGHT_YEAR = 1993
TAGLETAPI_FIRST_COPYRIGHT_YEAR = 1993
JDI_FIRST_COPYRIGHT_YEAR = 1999
JAAS_FIRST_COPYRIGHT_YEAR = 1998
JGSS_FIRST_COPYRIGHT_YEAR = 2000
SMARTCARDIO_FIRST_COPYRIGHT_YEAR = 2005
HTTPSERVER_FIRST_COPYRIGHT_YEAR = 2005
MGMT_FIRST_COPYRIGHT_YEAR = 2003
ATTACH_FIRST_COPYRIGHT_YEAR = 2005
JCONSOLE_FIRST_COPYRIGHT_YEAR = 2006
SCTPAPI_FIRST_COPYRIGHT_YEAR = 2009
TRACING_FIRST_COPYRIGHT_YEAR = 2008
TREEAPI_FIRST_COPYRIGHT_YEAR = 2005
JNLP_FIRST_COPYRIGHT_YEAR = 1998
PLUGIN2_FIRST_COPYRIGHT_YEAR = 2007

# Oracle name
FULL_COMPANY_NAME = Oracle and/or its affiliates

# Copyright address
COMPANY_ADDRESS = 500 Oracle Parkway<br>Redwood Shores, CA 94065 USA.

# The trademark symbol
TRADEMARK = ™

# Common copyright lines used
# The word "Copyright" might optionally be a link to the file cpyr.html.
# The first year of copyright may vary or not be available.
# The address to the company might be optional.
COMMA:= ,
EMPTY:=
SPACE:=$(EMPTY) $(EMPTY)
COPYRIGHT_SYMBOL = &\#x00a9;
# Macro to construct the copyright line
# (The GNU make 3.78.1 "if" conditional is broken, fixed in GNU make 3.81)
define CopyrightLine # optionalurl optionalfirstyear optionaladdress
$(if $(strip $1),<a href="$(strip $1)">Copyright,Copyright) \
$(COPYRIGHT_SYMBOL) $(if $2,$2${COMMA},) $(COPYRIGHT_YEAR),\
$(FULL_COMPANY_NAME). $3 All rights reserved.
endef

# Url to root of documents
DOCSDIR_URL = {@docroot}/$(GET2DOCSDIR)

# Url to copyright html file
COPYRIGHT_URL-7 = $(DOCSDIR_URL)/legal/cpyr.html
# This isn't added in old build yet.
#COPYRIGHT_URL-8 = $(DOCSDIR_URL)/legal/cpyr.html
COPYRIGHT_URL = $(COPYRIGHT_URL-$(JDK_MINOR_VERSION))

# Url to bug filing site
BUG_SUBMIT_URL = http://bugreport.sun.com/bugreport/

# Common line for how to submit a bug or rfe
BUG_SUBMIT_LINE = <a href="$(BUG_SUBMIT_URL)">Submit a bug or feature

# Url to devdocs page
# Was: http://java.sun.com/javase/6/webnotes/devdocs-vs-specs.html
DEV_DOCS_URL-7 = http://download.oracle.com/javase/7/docs/index.html
DEV_DOCS_URL-8 = http://download.oracle.com/javase/8/docs/index.html
DEV_DOCS_URL = $(DEV_DOCS_URL-$(JDK_MINOR_VERSION))
DOCS_BASE_URL = http://download.oracle.com/javase/7/docs

# Common Java trademark line
JAVA_TRADEMARK_LINE = Java is a trademark or registered trademark of \
$(FULL_COMPANY_NAME) in the US and other countries.

#################################################################
# Macros:


# List of all possible directories for javadoc to look for sources
# NOTE: Quotes are required around sourcepath argument only on Windows.
# Otherwise, you get "No packages or classes specified." due
# to $(PATH_SEP) being interpreted as an end of
# command (newline or shell ; character)
ALL_SOURCE_DIRS = $(JDK_SHARE_CLASSES) \
    $(JDK_IMPSRC) \
    $(JDK_GENSRC) \
    $(JDK_OUTPUTDIR)/gendocsrc_rmic \
    $(JDK_TOPDIR)/src/solaris/classes \
    $(JDK_TOPDIR)/src/windows/classes \
    $(JDK_SHARE_SRC)/doc/stub

# List of directories that actually exist
ALL_EXISTING_SOURCE_DIRS := $(wildcard $(ALL_SOURCE_DIRS))

# List with classpath separator between them
EMPTY:=
SPACE:= $(EMPTY) $(EMPTY)
RELEASEDOCS_SOURCEPATH = \
    $(subst $(SPACE),$(PATH_SEP),$(strip $(ALL_SOURCE_DIRS)))

define prep-target
	$(MKDIR) -p $(@D)
	$(RM) $@
endef

# Prep for javadoc creation, assumes $@ is an index.html file
define prep-javadoc
	@if [ -f "$@" -a "$?" != "" ] ; then \
	  $(ECHO) "# Dependencies have changed: $?"; \
	fi
	$(RM) -r $(@D)
	$(MKDIR) -p $(@D)
endef

# A cache of the directories in ALL_SOURCE_DIRS
DIRECTORY_CACHE = $(DOCSTMPDIR)/directory.cache

# Given a list of packages, return a list of files or dirs to be dependent on
# (Currently only returning a list of directories)
define PackageDependencies # packages
  $(shell \
      if [ "$1" != "" -a -f $(DIRECTORY_CACHE) ] ; then \
        for p in $1 ; do \
          pd=`$(ECHO) $${p} | $(SED) -e 's@[.]@/@g'`; \
          $(CAT) $(DIRECTORY_CACHE) | $(GREP) "/$${pd}/" ; \
        done; \
      fi \
  )
endef

# Given a list of packages, add packages that exist to $@, print summary
define PackageFilter # packages
	@if [ "$1" != "" ] ; then \
	  for p in $1 ; do \
	    pd=`$(ECHO) $${p} | $(SED) -e 's@[.]@/@g'`; \
	    found="false"; \
	    for cp in $(ALL_SOURCE_DIRS) ; do \
	      if [ -d $${cp}/$${pd} ] ; then \
	        $(ECHO) "$${p}" >> $@; \
	        found="true"; \
	        break; \
	      fi; \
	    done; \
	    if [ "$${found}" = "false" ] ; then \
	      $(ECHO) "WARNING: Package not found: $${p}"; \
	    fi; \
	  done; \
	fi
endef

# Print out a summary of the javadoc command about to be run
define JavadocSummary # optionsfile packagesfile
	@$(ECHO) "# Summary for $@"; \
	$(ECHO) "# Options (`$(BASENAME) $1`):"; $(SED) -e 's@^@#   @' $1; \
	$(ECHO) "# Packages (`$(BASENAME) $2`):";$(SED) -e 's@^@#   @' $2
endef

#
# Temporary directory for javadoc creation
#
DOCSTMPDIR = $(TEMPDIR)/doctmp

#
# Different api directories created from root directory
#
COREAPI_DOCSDIR = $(DOCSDIR)/api
JDK_API_DOCSDIR = $(DOCSDIR)/jdk/api
JRE_API_DOCSDIR = $(DOCSDIR)/jre/api
PLATFORM_DOCSDIR = $(DOCSDIR)/platform

# The non-core api javadocs need to be able to access the root of the core
# api directory, so for jdk/api or jre/api to get to the core api/
# directory we would use this:
JDKJRE2COREAPI = ../../api

# Common bottom argument
define CommonBottom # year
<font size="-1">
 $(call CopyrightLine,,$1,)
endef

# Common trademark bottom argument (Not sure why this is used sometimes)
define CommonTrademarkBottom # year
<font size="-1">\
$(BUG_SUBMIT_LINE)<br>$(JAVA_TRADEMARK_LINE)
\
$(call CopyrightLine,,$1,$(COMPANY_ADDRESS))\
</font>
endef

# Common echo of option
define OptionOnly # opt
	$(PRINTF) "%s\n" "$1"
endef
define OptionPair # opt arg
	$(PRINTF) "%s '%s'\n" "$1" '$2'
endef
define OptionTrip # opt arg arg
	$(PRINTF) "%s '%s' '%s'\n" "$1" '$2' '$3'
endef

# Core api bottom argument (with special sauce)
COREAPI_BOTTOM = <font size="-1"> $(BUG_SUBMIT_LINE)\
<br>For further API reference and developer documentation, \
see <a href="$(DEV_DOCS_URL)" target="_blank">Java SE Documentation. \
That documentation contains more detailed, developer-targeted descriptions, \
with conceptual overviews, definitions of terms, workarounds, \
and working code examples.<br>\
$(call CopyrightLine,$(COPYRIGHT_URL),$(FIRST_COPYRIGHT_YEAR),)\
</font>

# Common javadoc options used by all
COMMON_JAVADOCFLAGS = \
    -XDignore.symbol.file=true \
    -quiet \
    -use \
    -keywords \
    -Xdoclint:none \
    -Xprofilespath $(JDK_TOPDIR)/make/profile-rtjar-includes.txt \
    $(ADDITIONAL_JAVADOCFLAGS)

ifdef OPENJDK
  ADDITIONAL_JAVADOCFLAGS = \
      -Xdocrootparent $(DOCS_BASE_URL)
else
  ADDITIONAL_JAVADOCFLAGS =
endif

# Draft used for non-fcs documents
DRAFT_HEADER =
ifneq ($(MILESTONE), fcs)
  DRAFT_HEADER = <br>DRAFT $(MILESTONE)-$(BUILD_NUMBER)
  DRAFT_BOTTOM = <br>DRAFT $(MILESTONE)-$(BUILD_NUMBER)
  DRAFT_WINTITLE = $(BUILD_NUMBER)
  # Early access top text (not used in FCS releases)
  COREAPI_TOP_EARLYACCESS = \
<div style="background-color: \#EEEEEE"> \
<div style="padding: 6px; margin-top: 2px; margin-bottom: 6px; \
margin-left: 6px; margin-right: 6px; text-align: justify; \
font-size: 80%; font-family: Helvetica, Arial, sans-serif; \
font-weight: normal;"> \
Please note that the specifications and other information \
contained herein are not final and are subject to change. \
The information is being made available to you solely for purpose of \
evaluation. \
</div> 

Other Java examples (source code examples)

Here is a short list of links related to this Java Javadoc.gmk source code file:

•  The search page
•  Other Java source code examples at this package level
•  Click here to learn more about this project