Mercurial Mercurial > jdk-sandbox / changeset
summary | shortlog | changelog | graph | tags | bookmarks | branches | files | changeset | raw | help
Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
8051010: Support @apiNote, @implSpec and @implNote in all javadoc bundles
authormduigou
Mon, 21 Jul 2014 21:34:29 -0700
changeset 25614 0d18591d71d8
parent 25461 2842cbf0da97
child 25618 0d4a96093222
8051010: Support @apiNote, @implSpec and @implNote in all javadoc bundles Reviewed-by: alanb
make/Javadoc.gmk file | annotate | diff | comparison | revisions 
--- a/make/Javadoc.gmk	Tue Jul 15 21:45:50 2014 -0700
+++ b/make/Javadoc.gmk	Mon Jul 21 21:34:29 2014 -0700
@@ -239,11 +239,15 @@
 
 # Common echo of option
 define OptionOnly # opt
-	$(PRINTF) "%s\n" "$1"
+	if [ "$1" != "" ] ; then \
+		$(PRINTF) "%s\n" "$1"; \
+	fi
 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
@@ -258,14 +262,7 @@
 $(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)
+# Common javadoc options used by all bundles
 
 ifdef OPENJDK
   ADDITIONAL_JAVADOCFLAGS = \
@@ -274,6 +271,52 @@
   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 bundles
+
+# Java language specification cite
+TAG_JLS = jls:a:See <cite> \
+The Java&trade; Language Specification</cite>:
+
+# Java virtual machine specification cite
+TAG_JVMS = jvms:a:See <cite> \
+The Java&trade; 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)
@@ -338,10 +381,6 @@
 COREAPI_HEADER = \
 <strong>Java$(TRADEMARK)&nbsp;Platform<br>Standard&nbsp;Ed.&nbsp;$(JDK_MINOR_VERSION)</strong>
 
-# Java language specification cite
-TAG_JLS = jls:a:See <cite> \
-The Java&trade; Language Specification</cite>:
-
 # Overview file for core apis
 COREAPI_OVERVIEW = $(JDK_SHARE_CLASSES)/overview-core.html
 
@@ -365,29 +404,11 @@
 # Create file with javadoc options in it
 $(COREAPI_OPTIONS_FILE): $(COREAPI_OVERVIEW)
 	$(prep-target)
-	@($(call OptionOnly,$(COMMON_JAVADOCFLAGS)) ; \
-	  $(call OptionOnly,-Xdoclint:none) ; \
+	@($(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)) ; \
@@ -441,7 +462,8 @@
 # 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) ; \
@@ -498,7 +520,8 @@
 # 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) ; \
@@ -550,7 +573,8 @@
 # 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) ; \
@@ -613,7 +637,8 @@
 # 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) ; \
@@ -700,7 +725,8 @@
 # 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) ; \
@@ -753,7 +779,8 @@
 # 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) ; \
@@ -806,7 +833,8 @@
 # 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) ; \
@@ -857,7 +885,8 @@
 # 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) ; \
@@ -917,7 +946,8 @@
 # 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) ; \
@@ -969,7 +999,8 @@
 # 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) ; \
@@ -1020,7 +1051,8 @@
 # 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) ; \
@@ -1073,14 +1105,14 @@
 # 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)/); \
@@ -1125,7 +1157,8 @@
 # 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) ; \
@@ -1176,7 +1209,8 @@
 # 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) ; \
jdk-sandbox