8189056: javadoc target for stable specdiff comparisons

Reviewed-by: erikj
JasonFengJ9 · Oct 23, 2017 · 373e208 · 373e208
1 parent cb79884
commit 373e208
Show file tree

Hide file tree

Showing 5 changed files with 234 additions and 31 deletions.
diff --git a/make/Docs.gmk b/make/Docs.gmk
@@ -97,6 +97,11 @@ JAVADOC_TAGS := \
     $(CUSTOM_JAVADOC_TAGS) \
     #
 
+# The reference tags must stay stable to allow for comparisons across the
+# development cycle. If JAVADOC_TAGS needs to change, make sure that
+# REFERENCE_TAGS remains unchanged, by copying and hardcoding, if necessary.
+REFERENCE_TAGS := $(JAVADOC_TAGS)
+
 # Which doclint checks to ignore
 JAVADOC_DISABLED_DOCLINT := accessibility html missing syntax reference
 
@@ -106,6 +111,12 @@ JAVADOC_OPTIONS := -use -keywords -notimestamp \
     -splitIndex --system none -html5 -javafx --expand-requires transitive \
     --override-methods=summary
 
+# The reference options must stay stable to allow for comparisons across the
+# development cycle.
+REFERENCE_OPTIONS := -XDignore.symbol.file=true -use -keywords -notimestamp \
+    -serialwarn -encoding ISO-8859-1 -breakiterator -splitIndex --system none \
+    -html5 -javafx --expand-requires transitive
+
 # Should we add DRAFT stamps to the generated javadoc?
 ifeq ($(VERSION_IS_GA), true)
   IS_DRAFT := false
@@ -130,6 +141,11 @@ ifeq ($(IS_DRAFT), true)
   endif
   DRAFT_TEXT := This specification is not final and is subject to change. \
       Use is subject to <a href="$(LICENSE_URL)">license terms</a>.
+
+  # Workaround stylesheet bug
+  HEADER_STYLE := style="margin-top: 9px;"
+else
+  HEADER_STYLE := style="margin-top: 14px;"
 endif
 
 JAVADOC_BOTTOM := \
@@ -148,12 +164,19 @@ JAVADOC_BOTTOM := \
     <a href="$(REDISTRIBUTION_URL)">documentation redistribution policy</a>. \
     $(DRAFT_MARKER_STR) <!-- Version $(VERSION_STRING) -->
 
-
 JAVADOC_TOP := \
     <div style="padding: 6px; text-align: center; font-size: 80%; \
     font-family: DejaVu Sans, Arial, Helvetica, sans-serif; \
     font-weight: normal;">$(DRAFT_TEXT)</div>
 
+JDK_INDEX_CONTENT := \
+    <!DOCTYPE html> \
+    <html lang="en"> \
+    <head> \
+    <meta http-equiv="refresh" content="0;url=api/index.html"> \
+    </head> \
+    </html>
+
 ################################################################################
 # JDK javadoc titles/text snippets
 
@@ -258,8 +281,14 @@ define SetupApiDocsGenerationBody
     $1_JAVA_ARGS += -DenableModuleGraph=true
   endif
 
-  # Always include tags and basic options
-  $1_OPTIONS := $$(JAVADOC_TAGS) $$(JAVADOC_OPTIONS)
+  # Start with basic options and tags
+  ifeq ($$($1_OPTIONS), )
+    $1_OPTIONS := $$(JAVADOC_OPTIONS)
+  endif
+  ifeq ($$($1_TAGS), )
+    $1_TAGS := $$(JAVADOC_TAGS)
+  endif
+  $1_OPTIONS += $$($1_TAGS)
 
   $1_OPTIONS += --module-source-path $$(MODULES_SOURCE_PATH)
   $1_OPTIONS += --module $$(call CommaList, $$($1_MODULES))
@@ -268,15 +297,10 @@ define SetupApiDocsGenerationBody
   $1_OPTIONS += -Xdoclint:all,$$(call CommaList, $$(addprefix -, \
       $$(JAVADOC_DISABLED_DOCLINT)))
 
-  $1_DOC_TITLE := $$($1_LONG_NAME)<br>Version $$(VERSION_SPECIFICATION) API Specification
-  $1_WINDOW_TITLE := $$(subst &amp;,&,$$($1_SHORT_NAME)) \
-    $$(DRAFT_MARKER_TITLE)
-  ifeq ($(VERSION_IS_GA), true) # Workaround stylesheet bug
-    $1_HEADER_PAD := 14
-  else
-    $1_HEADER_PAD := 9
-  endif
-  $1_HEADER_TITLE := <div style="margin-top: $$($1_HEADER_PAD)px;"><strong>$$($1_SHORT_NAME)</strong> \
+  $1_DOC_TITLE := $$($1_LONG_NAME)<br>Version $$(VERSION_SPECIFICATION) API \
+      Specification
+  $1_WINDOW_TITLE := $$(subst &amp;,&,$$($1_SHORT_NAME)) $$(DRAFT_MARKER_TITLE)
+  $1_HEADER_TITLE := <div $$(HEADER_STYLE)><strong>$$($1_SHORT_NAME)</strong> \
       $$(DRAFT_MARKER_STR)</div>
 
   $1_OPTIONS += -doctitle '$$($1_DOC_TITLE)'
@@ -303,8 +327,13 @@ define SetupApiDocsGenerationBody
     $$(eval $1_OPTIONS += -group "$$($$g_GROUP_NAME)" "$$($$g_GROUP_MODULES)") \
   )
 
+  ifeq ($$($1_JAVADOC_CMD), )
+    $1_JAVADOC_CMD := $$(JAVA) -Djava.awt.headless=true $$($1_JAVA_ARGS) \
+        $$(NEW_JAVADOC)
+  endif
+
   $1_VARDEPS := $$($1_JAVA_ARGS) $$($1_OPTIONS) $$(MODULES_SOURCE_PATH) \
-      $$($1_ALL_MODULES)
+      $$($1_ALL_MODULES) $$($1_JAVADOC_CMD)
   $1_VARDEPS_FILE := $$(call DependOnVariable, $1_VARDEPS, \
       $$(SUPPORT_OUTPUTDIR)/docs/$1.vardeps)
 
@@ -320,9 +349,8 @@ define SetupApiDocsGenerationBody
 	$$(call LogInfo, Javadoc modules: $$($1_ALL_MODULES))
 	$$(call MakeDir, $$($1_TARGET_DIR))
 	$$(call ExecuteWithLog, $$(SUPPORT_OUTPUTDIR)/docs/$1, \
-	    $$(JAVA) -Djava.awt.headless=true $$($1_JAVA_ARGS) \
-	        $$(NEW_JAVADOC) -d $$($1_TARGET_DIR) \
-	        $$(JAVADOC_TAGS) $$($1_OPTIONS) $$($1_LOG_OPTION))
+	    $$($1_JAVADOC_CMD) -d $$($1_TARGET_DIR) \
+	        $$($1_OPTIONS) $$($1_LOG_OPTION))
 
   $1_JAVADOC_TARGETS := $$($1_TARGET_DIR)/index.html
 
@@ -432,18 +460,29 @@ $(eval $(call SetupApiDocsGeneration, JAVASE_API, \
 # JAVASE_API_MODULEGRAPH_TARGETS.
 
 ################################################################################
+# Setup generation of the reference Java SE API documentation (javadoc + modulegraph)
 
-JDK_INDEX_HTML := $(DOCS_OUTPUTDIR)/index.html
+# The reference javadoc is just the same as javase, but using the BootJDK javadoc
+# and a stable set of javadoc options.
 
-JDK_INDEX_CONTENT := \
-    <!DOCTYPE html> \
-    <html lang="en"> \
-    <head> \
-    <meta http-equiv="refresh" content="0;url=api/index.html"> \
-    </head> \
-    </html>
+$(eval $(call SetupApiDocsGeneration, REFERENCE_API, \
+    MODULES := $(JAVASE_MODULES), \
+    SHORT_NAME := $(JAVASE_SHORT_NAME), \
+    LONG_NAME := $(JAVASE_LONG_NAME), \
+    TARGET_DIR := $(IMAGES_OUTPUTDIR)/reference-docs/api, \
+    JAVADOC_CMD := $(JAVADOC), \
+    OPTIONS := $(REFERENCE_OPTIONS), \
+    TAGS := $(REFERENCE_TAGS), \
+))
+
+# Targets generated are returned in REFERENCE_API_JAVADOC_TARGETS and
+# REFERENCE_API_MODULEGRAPH_TARGETS.
+
+################################################################################
 
-$(JDK_INDEX_HTML): 
+JDK_INDEX_HTML := $(DOCS_OUTPUTDIR)/index.html
+
+$(JDK_INDEX_HTML):
 	$(ECHO) '$(JDK_INDEX_CONTENT)' > $@
 
 JDK_INDEX_TARGETS += $(JDK_INDEX_HTML)
@@ -554,15 +593,21 @@ docs-javase-api-javadoc: $(JAVASE_API_JAVADOC_TARGETS) $(JAVASE_API_CUSTOM_TARGE
 
 docs-javase-api-modulegraph: $(JAVASE_API_MODULEGRAPH_TARGETS)
 
+docs-reference-api-javadoc: $(REFERENCE_API_JAVADOC_TARGETS) $(REFERENCE_API_CUSTOM_TARGETS)
+
+docs-reference-api-modulegraph: $(REFERENCE_API_MODULEGRAPH_TARGETS)
+
 docs-jdk-specs: $(JDK_SPECS_TARGETS)
 
 docs-jdk-index: $(JDK_INDEX_TARGETS)
 
 docs-zip: $(ZIP_TARGETS)
 
 all: docs-jdk-api-javadoc docs-jdk-api-modulegraph docs-javase-api-javadoc \
-    docs-javase-api-modulegraph docs-jdk-specs docs-jdk-index docs-zip
+    docs-javase-api-modulegraph docs-reference-api-javadoc \
+    docs-reference-api-modulegraph docs-jdk-specs docs-jdk-index docs-zip
 
 .PHONY: default all docs-jdk-api-javadoc docs-jdk-api-modulegraph \
-    docs-javase-api-javadoc docs-javase-api-modulegraph docs-jdk-specs \
+    docs-javase-api-javadoc docs-javase-api-modulegraph \
+    docs-reference-api-javadoc docs-reference-api-modulegraph docs-jdk-specs \
     docs-jdk-index docs-zip
diff --git a/make/Main.gmk b/make/Main.gmk
@@ -382,6 +382,12 @@ docs-javase-api-javadoc:
 docs-javase-api-modulegraph:
 	+($(CD) $(TOPDIR)/make && $(MAKE) $(MAKE_ARGS) -f Docs.gmk docs-javase-api-modulegraph)
 
+docs-reference-api-javadoc:
+	+($(CD) $(TOPDIR)/make && $(MAKE) $(MAKE_ARGS) -f Docs.gmk docs-reference-api-javadoc)
+
+docs-reference-api-modulegraph:
+	+($(CD) $(TOPDIR)/make && $(MAKE) $(MAKE_ARGS) -f Docs.gmk docs-reference-api-modulegraph)
+
 docs-jdk-specs:
 	+($(CD) $(TOPDIR)/make && $(MAKE) $(MAKE_ARGS) -f Docs.gmk docs-jdk-specs)
 
@@ -395,7 +401,8 @@ update-build-docs:
 	+($(CD) $(TOPDIR)/make && $(MAKE) $(MAKE_ARGS) -f UpdateBuildDocs.gmk)
 
 ALL_TARGETS += docs-jdk-api-javadoc docs-jdk-api-modulegraph \
-    docs-javase-api-javadoc docs-javase-api-modulegraph docs-jdk-specs \
+    docs-javase-api-javadoc docs-javase-api-modulegraph \
+    docs-reference-api-javadoc docs-reference-api-modulegraph docs-jdk-specs \
     docs-jdk-index docs-zip update-build-docs
 
 ################################################################################
@@ -810,10 +817,14 @@ else
 
   docs-javase-api-javadoc: $(GENSRC_TARGETS) rmic
 
+  docs-reference-api-javadoc: $(GENSRC_TARGETS) rmic
+
   docs-jdk-api-modulegraph: exploded-image buildtools-modules
 
   docs-javase-api-modulegraph: exploded-image buildtools-modules
 
+  docs-reference-api-modulegraph: exploded-image buildtools-modules
+
   # The gensrc steps for hotspot and jdk.jdi create html spec files.
   docs-jdk-specs: hotspot-$(JVM_VARIANT_MAIN)-gensrc jdk.jdi-gensrc \
       docs-jdk-index
@@ -943,16 +954,19 @@ create-buildjdk: create-buildjdk-copy create-buildjdk-interim-image
 
 docs-jdk-api: docs-jdk-api-javadoc
 docs-javase-api: docs-javase-api-javadoc
+docs-reference-api: docs-reference-api-javadoc
 
 # If we're building full docs, we must also generate the module graphs to
 # get non-broken api documentation.
 ifeq ($(ENABLE_FULL_DOCS), true)
   docs-jdk-api: docs-jdk-api-modulegraph
   docs-javase-api: docs-javase-api-modulegraph
+  docs-reference-api: docs-reference-api-modulegraph
 endif
 
 docs-jdk: docs-jdk-api docs-jdk-specs docs-jdk-index
 docs-javase: docs-javase-api
+docs-reference: docs-reference-api
 
 # alias for backwards compatibility
 docs-javadoc: docs-jdk-api
@@ -1005,8 +1019,8 @@ ALL_TARGETS += buildtools hotspot hotspot-libs hotspot-gensrc gensrc gendata \
     copy java rmic libs launchers jmods \
     jdk.jdwp.agent-gensrc $(ALL_MODULES) demos \
     exploded-image-base exploded-image \
-    create-buildjdk docs-jdk-api docs-javase-api docs-jdk docs-javase \
-    docs-javadoc mac-bundles product-images \
+    create-buildjdk docs-jdk-api docs-javase-api docs-reference-api docs-jdk \
+    docs-javase docs-reference docs-javadoc mac-bundles product-images \
     profiles profiles-images \
     docs-image test-image all-images \
     all-bundles

diff --git a/make/autoconf/boot-jdk.m4 b/make/autoconf/boot-jdk.m4
@@ -296,6 +296,7 @@ AC_DEFUN_ONCE([BOOTJDK_SETUP_BOOT_JDK],
   BOOTJDK_CHECK_TOOL_IN_BOOTJDK(JAVA, java)
   BOOTJDK_CHECK_TOOL_IN_BOOTJDK(JAVAC, javac)
   BOOTJDK_CHECK_TOOL_IN_BOOTJDK(JAVAH, javah)
+  BOOTJDK_CHECK_TOOL_IN_BOOTJDK(JAVADOC, javadoc)
   BOOTJDK_CHECK_TOOL_IN_BOOTJDK(JAR, jar)
   BOOTJDK_CHECK_TOOL_IN_BOOTJDK(JARSIGNER, jarsigner)