make/Javadoc.gmk
Print this page
rev 1103 : 8051010: Support @apiNote, @implSpec and @implNote in all javadoc bundles
Reviewed-by: duke
@@ -239,13 +239,15 @@
# 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)
@@ -257,25 +259,63 @@
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 \
- -Xprofilespath $(JDK_TOPDIR)/make/profile-rtjar-includes.txt \
- $(ADDITIONAL_JAVADOCFLAGS)
ifdef OPENJDK
ADDITIONAL_JAVADOCFLAGS = \
-Xdocrootparent $(DOCS_BASE_URL)
else
ADDITIONAL_JAVADOCFLAGS =
endif
+define COMMON_JAVADOCFLAGS
+ $(call OptionOnly,-XDignore.symbol.file=true) ; \
+ $(call OptionOnly,-quiet) ; \
+ $(call OptionOnly,-use) ; \
+ $(call OptionOnly,-keywords) ; \
+ $(call OptionPair,-Xprofilespath,$(JDK_TOPDIR)/make/profile-rtjar-includes.txt) ; \
+ $(call OptionOnly,$(ADDITIONAL_JAVADOCFLAGS))
+endef
+
+# Common javadoc tags used by all
+# Java language specification cite
+TAG_JLS = jls:a:See <cite> \
+The Java™ Language Specification</cite>:
+
+# Java virtual machine specification cite
+TAG_JVMS = jvms:a:See <cite> \
+The Java™ Virtual Machine Specification</cite>:
+
+# In order to get a specific ordering it's necessary to specify the total
+# ordering of tags as the tags are otherwise ordered in order of definition.
+define COMMON_JAVADOCTAGS
+ $(call OptionPair,-tag,beaninfo:X) ; \
+ $(call OptionPair,-tag,revised:X) ; \
+ $(call OptionPair,-tag,since.unbundled:X) ; \
+ $(call OptionPair,-tag,spec:X) ; \
+ $(call OptionPair,-tag,specdefault:X) ; \
+ $(call OptionPair,-tag,Note:X) ; \
+ $(call OptionPair,-tag,ToDo:X) ; \
+ $(call OptionPair,-tag,apiNote:a:API Note:) ; \
+ $(call OptionPair,-tag,implSpec:a:Implementation Requirements:) ; \
+ $(call OptionPair,-tag,implNote:a:Implementation Note:) ; \
+ $(call OptionPair,-tag,param) ; \
+ $(call OptionPair,-tag,return) ; \
+ $(call OptionPair,-tag,throws) ; \
+ $(call OptionPair,-tag,since) ; \
+ $(call OptionPair,-tag,version) ; \
+ $(call OptionPair,-tag,serialData) ; \
+ $(call OptionPair,-tag,factory) ; \
+ $(call OptionPair,-tag,see) ; \
+ $(call OptionPair,-tag,$(TAG_JVMS)) ; \
+ $(call OptionPair,-tag,$(TAG_JLS))
+endef
+
+
+
# Draft used for non-fcs documents
DRAFT_HEADER =
ifneq ($(MILESTONE), fcs)
DRAFT_HEADER = <br><strong>DRAFT $(MILESTONE)-$(BUILD_NUMBER)</strong>
DRAFT_BOTTOM = <br><strong>DRAFT $(MILESTONE)-$(BUILD_NUMBER)</strong>
@@ -336,14 +376,10 @@
$(JDK_MINOR_VERSION)<br>API Specification
COREAPI_WINDOWTITLE = Java Platform SE $(JDK_MINOR_VERSION)
COREAPI_HEADER = \
<strong>Java$(TRADEMARK) Platform<br>Standard Ed. $(JDK_MINOR_VERSION)</strong>
-# Java language specification cite
-TAG_JLS = jls:a:See <cite> \
-The Java™ Language Specification</cite>:
-
# Overview file for core apis
COREAPI_OVERVIEW = $(JDK_SHARE_CLASSES)/overview-core.html
# The index.html, options, and packages files
COREAPI_INDEX_FILE = $(COREAPI_DOCSDIR)/index.html
@@ -363,33 +399,15 @@
@$(COREAPI_OPTIONS_FILE) @$(COREAPI_PACKAGES_FILE)
# Create file with javadoc options in it
$(COREAPI_OPTIONS_FILE): $(COREAPI_OVERVIEW)
$(prep-target)
- @($(call OptionOnly,$(COMMON_JAVADOCFLAGS)) ; \
+ @($(call COMMON_JAVADOCFLAGS) ; \
+ $(call COMMON_JAVADOCTAGS) ; \
$(call OptionOnly,-Xdoclint:none) ; \
$(call OptionPair,-sourcepath,$(RELEASEDOCS_SOURCEPATH)) ; \
$(call OptionPair,-encoding,ISO-8859-1) ; \
- $(call OptionPair,-tag,beaninfo:X) ; \
- $(call OptionPair,-tag,revised:X) ; \
- $(call OptionPair,-tag,since.unbundled:X) ; \
- $(call OptionPair,-tag,spec:X) ; \
- $(call OptionPair,-tag,specdefault:X) ; \
- $(call OptionPair,-tag,Note:X) ; \
- $(call OptionPair,-tag,ToDo:X) ; \
- $(call OptionPair,-tag,apiNote:a:API Note:) ; \
- $(call OptionPair,-tag,implSpec:a:Implementation Requirements:) ; \
- $(call OptionPair,-tag,implNote:a:Implementation Note:) ; \
- $(call OptionPair,-tag,param) ; \
- $(call OptionPair,-tag,return) ; \
- $(call OptionPair,-tag,throws) ; \
- $(call OptionPair,-tag,since) ; \
- $(call OptionPair,-tag,version) ; \
- $(call OptionPair,-tag,serialData) ; \
- $(call OptionPair,-tag,factory) ; \
- $(call OptionPair,-tag,see) ; \
- $(call OptionPair,-tag,$(TAG_JLS)) ; \
$(call OptionOnly,-splitIndex) ; \
$(call OptionPair,-overview,$(COREAPI_OVERVIEW)) ; \
$(call OptionPair,-doctitle,$(COREAPI_DOCTITLE)) ; \
$(call OptionPair,-windowtitle,$(COREAPI_WINDOWTITLE) $(DRAFT_WINTITLE)) ; \
$(call OptionPair,-header,$(COREAPI_HEADER)$(DRAFT_HEADER)) ; \
@@ -439,11 +457,12 @@
@$(DOCLETAPI_OPTIONS_FILE) @$(DOCLETAPI_PACKAGES_FILE)
# Create file with javadoc options in it
$(DOCLETAPI_OPTIONS_FILE):
$(prep-target)
- @($(call OptionOnly,$(COMMON_JAVADOCFLAGS)) ; \
+ @($(call COMMON_JAVADOCFLAGS) ; \
+ $(call COMMON_JAVADOCTAGS) ; \
$(call OptionOnly,-Xdoclint:all) ; \
$(call OptionPair,-sourcepath,$(RELEASEDOCS_SOURCEPATH)) ; \
$(call OptionPair,-encoding,ascii) ; \
$(call OptionOnly,-breakiterator) ; \
$(call OptionPair,-doctitle,$(DOCLETAPI_DOCTITLE)) ; \
@@ -496,11 +515,12 @@
$(RM) -r $(TAGLETAPI_TEMPDIR)
# Create file with javadoc options in it
$(TAGLETAPI_OPTIONS_FILE):
$(prep-target)
- @($(call OptionOnly,$(COMMON_JAVADOCFLAGS)) ; \
+ @($(call COMMON_JAVADOCFLAGS) ; \
+ $(call COMMON_JAVADOCTAGS) ; \
$(call OptionOnly,-Xdoclint:all) ; \
$(call OptionPair,-sourcepath,$(RELEASEDOCS_SOURCEPATH)) ; \
$(call OptionPair,-encoding,ascii) ; \
$(call OptionOnly,-nonavbar) ; \
$(call OptionOnly,-noindex) ; \
@@ -548,11 +568,12 @@
@$(DOMAPI_OPTIONS_FILE) @$(DOMAPI_PACKAGES_FILE)
# Create file with javadoc options in it
$(DOMAPI_OPTIONS_FILE):
$(prep-target)
- @($(call OptionOnly,$(COMMON_JAVADOCFLAGS)) ; \
+ @($(call COMMON_JAVADOCFLAGS) ; \
+ $(call COMMON_JAVADOCTAGS) ; \
$(call OptionOnly,-Xdoclint:none) ; \
$(call OptionPair,-sourcepath,$(RELEASEDOCS_SOURCEPATH)) ; \
$(call OptionPair,-encoding,ascii) ; \
$(call OptionOnly,-splitIndex) ; \
$(call OptionPair,-doctitle,$(DOMAPI_DOCTITLE)) ; \
@@ -611,11 +632,12 @@
@$(JDI_OPTIONS_FILE) @$(JDI_PACKAGES_FILE)
# Create file with javadoc options in it
$(JDI_OPTIONS_FILE): $(JDI_OVERVIEW)
$(prep-target)
- @($(call OptionOnly,$(COMMON_JAVADOCFLAGS)) ; \
+ @($(call COMMON_JAVADOCFLAGS) ; \
+ $(call COMMON_JAVADOCTAGS) ; \
$(call OptionOnly,-Xdoclint:none) ; \
$(call OptionPair,-sourcepath,$(RELEASEDOCS_SOURCEPATH)) ; \
$(call OptionPair,-encoding,ascii) ; \
$(call OptionPair,-overview,$(JDI_OVERVIEW)) ; \
$(call OptionPair,-doctitle,$(JDI_DOCTITLE)) ; \
@@ -698,11 +720,12 @@
@$(JAAS_OPTIONS_FILE) @$(JAAS_PACKAGES_FILE)
# Create file with javadoc options in it
$(JAAS_OPTIONS_FILE): $(JAAS_OVERVIEW)
$(prep-target)
- @($(call OptionOnly,$(COMMON_JAVADOCFLAGS)) ; \
+ @($(call COMMON_JAVADOCFLAGS) ; \
+ $(call COMMON_JAVADOCTAGS) ; \
$(call OptionOnly,-Xdoclint:none) ; \
$(call OptionPair,-sourcepath,$(RELEASEDOCS_SOURCEPATH)) ; \
$(call OptionPair,-encoding,ascii) ; \
$(call OptionPair,-overview,$(JAAS_OVERVIEW)) ; \
$(call OptionPair,-doctitle,$(JAAS_DOCTITLE)) ; \
@@ -751,11 +774,12 @@
@$(JGSS_OPTIONS_FILE) @$(JGSS_PACKAGES_FILE)
# Create file with javadoc options in it
$(JGSS_OPTIONS_FILE): $(JGSS_OVERVIEW)
$(prep-target)
- @($(call OptionOnly,$(COMMON_JAVADOCFLAGS)) ; \
+ @($(call COMMON_JAVADOCFLAGS) ; \
+ $(call COMMON_JAVADOCTAGS) ; \
$(call OptionOnly,-Xdoclint:none) ; \
$(call OptionPair,-sourcepath,$(RELEASEDOCS_SOURCEPATH)) ; \
$(call OptionPair,-encoding,ascii) ; \
$(call OptionOnly,-nodeprecatedlist) ; \
$(call OptionPair,-overview,$(JGSS_OVERVIEW)) ; \
@@ -804,11 +828,12 @@
@$(SMARTCARDIO_OPTIONS_FILE) @$(SMARTCARDIO_PACKAGES_FILE)
# Create file with javadoc options in it
$(SMARTCARDIO_OPTIONS_FILE):
$(prep-target)
- @($(call OptionOnly,$(COMMON_JAVADOCFLAGS)) ; \
+ @($(call COMMON_JAVADOCFLAGS) ; \
+ $(call COMMON_JAVADOCTAGS) ; \
$(call OptionOnly,-Xdoclint:none) ; \
$(call OptionPair,-sourcepath,$(RELEASEDOCS_SOURCEPATH)) ; \
$(call OptionPair,-encoding,ascii) ; \
$(call OptionOnly,-nodeprecatedlist) ; \
$(call OptionPair,-doctitle,$(SMARTCARDIO_DOCTITLE)) ; \
@@ -855,11 +880,12 @@
@$(HTTPSERVER_OPTIONS_FILE) @$(HTTPSERVER_PACKAGES_FILE)
# Create file with javadoc options in it
$(HTTPSERVER_OPTIONS_FILE):
$(prep-target)
- @($(call OptionOnly,$(COMMON_JAVADOCFLAGS)) ; \
+ @($(call COMMON_JAVADOCFLAGS) ; \
+ $(call COMMON_JAVADOCTAGS) ; \
$(call OptionOnly,-Xdoclint:none) ; \
$(call OptionPair,-sourcepath,$(RELEASEDOCS_SOURCEPATH)) ; \
$(call OptionPair,-encoding,ascii) ; \
$(call OptionOnly,-nodeprecatedlist) ; \
$(call OptionPair,-doctitle,$(HTTPSERVER_DOCTITLE)) ; \
@@ -915,11 +941,12 @@
@$(MGMT_OPTIONS_FILE) @$(MGMT_PACKAGES_FILE)
# Create file with javadoc options in it
$(MGMT_OPTIONS_FILE): $(MGMT_OVERVIEW)
$(prep-target)
- @($(call OptionOnly,$(COMMON_JAVADOCFLAGS)) ; \
+ @($(call COMMON_JAVADOCFLAGS) ; \
+ $(call COMMON_JAVADOCTAGS) ; \
$(call OptionOnly,-Xdoclint:none) ; \
$(call OptionPair,-sourcepath,$(RELEASEDOCS_SOURCEPATH)) ; \
$(call OptionPair,-encoding,ascii) ; \
$(call OptionOnly,-nodeprecatedlist) ; \
$(call OptionPair,-overview,$(MGMT_OVERVIEW)) ; \
@@ -967,11 +994,12 @@
@$(ATTACH_OPTIONS_FILE) @$(ATTACH_PACKAGES_FILE)
# Create file with javadoc options in it
$(ATTACH_OPTIONS_FILE):
$(prep-target)
- @($(call OptionOnly,$(COMMON_JAVADOCFLAGS)) ; \
+ @($(call COMMON_JAVADOCFLAGS) ; \
+ $(call COMMON_JAVADOCTAGS) ; \
$(call OptionOnly,-Xdoclint:none) ; \
$(call OptionPair,-sourcepath,$(RELEASEDOCS_SOURCEPATH)) ; \
$(call OptionPair,-encoding,ascii) ; \
$(call OptionOnly,-nodeprecatedlist) ; \
$(call OptionPair,-doctitle,$(ATTACH_DOCTITLE)) ; \
@@ -1018,11 +1046,12 @@
@$(JCONSOLE_OPTIONS_FILE) @$(JCONSOLE_PACKAGES_FILE)
# Create file with javadoc options in it
$(JCONSOLE_OPTIONS_FILE):
$(prep-target)
- @($(call OptionOnly,$(COMMON_JAVADOCFLAGS)) ; \
+ @($(call COMMON_JAVADOCFLAGS) ; \
+ $(call COMMON_JAVADOCTAGS) ; \
$(call OptionOnly,-Xdoclint:none) ; \
$(call OptionPair,-sourcepath,$(RELEASEDOCS_SOURCEPATH)) ; \
$(call OptionPair,-encoding,ascii) ; \
$(call OptionOnly,-nodeprecatedlist) ; \
$(call OptionPair,-doctitle,$(JCONSOLE_DOCTITLE)) ; \
@@ -1071,18 +1100,18 @@
@$(TREEAPI_OPTIONS_FILE) @$(TREEAPI_PACKAGES_FILE)
# Create file with javadoc options in it
$(TREEAPI_OPTIONS_FILE):
$(prep-target)
- @($(call OptionOnly,$(COMMON_JAVADOCFLAGS)) ; \
+ @($(call COMMON_JAVADOCFLAGS) ; \
+ $(call COMMON_JAVADOCTAGS) ; \
$(call OptionOnly,-Xdoclint:all) ; \
$(call OptionPair,-sourcepath,$(RELEASEDOCS_SOURCEPATH)) ; \
$(call OptionPair,-encoding,ascii) ; \
$(call OptionPair,-doctitle,$(TREEAPI_DOCTITLE)) ; \
$(call OptionPair,-windowtitle,$(TREEAPI_WINDOWTITLE) $(DRAFT_WINTITLE)); \
$(call OptionPair,-header,$(TREEAPI_HEADER)$(DRAFT_HEADER)) ; \
- $(call OptionPair,-tag,$(TAG_JLS)) ; \
$(call OptionPair,-bottom,$(TREEAPI_BOTTOM)$(DRAFT_BOTTOM)) ; \
$(call OptionTrip,-group,$(TREEAPI_GROUPNAME),$(TREEAPI_REGEXP)); \
$(call OptionTrip,-linkoffline,$(TREEAPI2COREAPI),$(COREAPI_DOCSDIR)/); \
) >> $@
@@ -1123,11 +1152,12 @@
@$(SCTPAPI_OPTIONS_FILE) @$(SCTPAPI_PACKAGES_FILE)
# Create file with javadoc options in it
$(SCTPAPI_OPTIONS_FILE):
$(prep-target)
- @($(call OptionOnly,$(COMMON_JAVADOCFLAGS)) ; \
+ @($(call COMMON_JAVADOCFLAGS) ; \
+ $(call COMMON_JAVADOCTAGS) ; \
$(call OptionOnly,-Xdoclint:none) ; \
$(call OptionPair,-sourcepath,$(RELEASEDOCS_SOURCEPATH)) ; \
$(call OptionPair,-encoding,ascii) ; \
$(call OptionOnly,-nodeprecatedlist) ; \
$(call OptionPair,-doctitle,$(SCTPAPI_DOCTITLE)) ; \
@@ -1174,11 +1204,12 @@
@$(JDKNET_OPTIONS_FILE) @$(JDKNET_PACKAGES_FILE)
# Create file with javadoc options in it
$(JDKNET_OPTIONS_FILE):
$(prep-target)
- @($(call OptionOnly,$(COMMON_JAVADOCFLAGS)) ; \
+ @($(call COMMON_JAVADOCFLAGS) ; \
+ $(call COMMON_JAVADOCTAGS) ; \
$(call OptionOnly,-Xdoclint:none) ; \
$(call OptionPair,-sourcepath,$(RELEASEDOCS_SOURCEPATH)) ; \
$(call OptionPair,-encoding,ascii) ; \
$(call OptionOnly,-nodeprecatedlist) ; \
$(call OptionPair,-doctitle,$(JDKNET_DOCTITLE)) ; \