changeset 47630:28d6070f5f2f

8189056: javadoc target for stable specdiff comparisons Reviewed-by: erikj
author ihse
date Mon, 23 Oct 2017 10:21:13 +0200
parents e6f53ff13373
children 6331ad007664
files make/Docs.gmk make/Main.gmk make/autoconf/boot-jdk.m4 make/autoconf/generated-configure.sh make/autoconf/spec.gmk.in
diffstat 5 files changed, 234 insertions(+), 31 deletions(-) [+]
line wrap: on
line diff
--- a/make/Docs.gmk	Sat Oct 21 00:06:31 2017 +0000
+++ b/make/Docs.gmk	Mon Oct 23 10:21:13 2017 +0200
@@ -97,6 +97,11 @@
     $(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 @@
     -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 @@
   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 @@
     <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 @@
     $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 @@
   $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 @@
     $$(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 @@
 	$$(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 @@
 # JAVASE_API_MODULEGRAPH_TARGETS.
 
 ################################################################################
+# Setup generation of the reference Java SE API documentation (javadoc + modulegraph)
+
+# The reference javadoc is just the same as javase, but using the BootJDK javadoc
+# and a stable set of javadoc options.
+
+$(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 := $(DOCS_OUTPUTDIR)/index.html
 
-JDK_INDEX_CONTENT := \
-    <!DOCTYPE html> \
-    <html lang="en"> \
-    <head> \
-    <meta http-equiv="refresh" content="0;url=api/index.html"> \
-    </head> \
-    </html>
-
-$(JDK_INDEX_HTML): 
+$(JDK_INDEX_HTML):
 	$(ECHO) '$(JDK_INDEX_CONTENT)' > $@
 
 JDK_INDEX_TARGETS += $(JDK_INDEX_HTML)
@@ -554,6 +593,10 @@
 
 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)
@@ -561,8 +604,10 @@
 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
--- a/make/Main.gmk	Sat Oct 21 00:06:31 2017 +0000
+++ b/make/Main.gmk	Mon Oct 23 10:21:13 2017 +0200
@@ -382,6 +382,12 @@
 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 @@
 	+($(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 @@
 
   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 @@
 
 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 @@
     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
--- a/make/autoconf/boot-jdk.m4	Sat Oct 21 00:06:31 2017 +0000
+++ b/make/autoconf/boot-jdk.m4	Mon Oct 23 10:21:13 2017 +0200
@@ -296,6 +296,7 @@
   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)
 
--- a/make/autoconf/generated-configure.sh	Sat Oct 21 00:06:31 2017 +0000
+++ b/make/autoconf/generated-configure.sh	Mon Oct 23 10:21:13 2017 +0200
@@ -881,6 +881,7 @@
 BOOT_JDK_SOURCETARGET
 JARSIGNER
 JAR
+JAVADOC
 JAVAH
 JAVAC
 JAVA
@@ -1294,6 +1295,7 @@
 JAVA
 JAVAC
 JAVAH
+JAVADOC
 JAR
 JARSIGNER
 CC
@@ -2237,6 +2239,7 @@
   JAVA        Override default value for JAVA
   JAVAC       Override default value for JAVAC
   JAVAH       Override default value for JAVAH
+  JAVADOC     Override default value for JAVADOC
   JAR         Override default value for JAR
   JARSIGNER   Override default value for JARSIGNER
   CC          C compiler command
@@ -5114,7 +5117,7 @@
 #CUSTOM_AUTOCONF_INCLUDE
 
 # Do not change or remove the following line, it is needed for consistency checks:
-DATE_WHEN_GENERATED=1508497666
+DATE_WHEN_GENERATED=1508746828
 
 ###############################################################################
 #
@@ -31174,6 +31177,144 @@
   # Publish this variable in the help.
 
 
+  if [ -z "${JAVADOC+x}" ]; then
+    # The variable is not set by user, try to locate tool using the code snippet
+
+      { $as_echo "$as_me:${as_lineno-$LINENO}: checking for javadoc in Boot JDK" >&5
+$as_echo_n "checking for javadoc in Boot JDK... " >&6; }
+      JAVADOC=$BOOT_JDK/bin/javadoc
+      if test ! -x $JAVADOC; then
+        { $as_echo "$as_me:${as_lineno-$LINENO}: result: not found" >&5
+$as_echo "not found" >&6; }
+        { $as_echo "$as_me:${as_lineno-$LINENO}: Your Boot JDK seems broken. This might be fixed by explicitly setting --with-boot-jdk" >&5
+$as_echo "$as_me: Your Boot JDK seems broken. This might be fixed by explicitly setting --with-boot-jdk" >&6;}
+        as_fn_error $? "Could not find javadoc in the Boot JDK" "$LINENO" 5
+      fi
+      { $as_echo "$as_me:${as_lineno-$LINENO}: result: ok" >&5
+$as_echo "ok" >&6; }
+
+
+  else
+    # The variable is set, but is it from the command line or the environment?
+
+    # Try to remove the string !JAVADOC! from our list.
+    try_remove_var=${CONFIGURE_OVERRIDDEN_VARIABLES//!JAVADOC!/}
+    if test "x$try_remove_var" = "x$CONFIGURE_OVERRIDDEN_VARIABLES"; then
+      # If it failed, the variable was not from the command line. Ignore it,
+      # but warn the user (except for BASH, which is always set by the calling BASH).
+      if test "xJAVADOC" != xBASH; then
+        { $as_echo "$as_me:${as_lineno-$LINENO}: WARNING: Ignoring value of JAVADOC from the environment. Use command line variables instead." >&5
+$as_echo "$as_me: WARNING: Ignoring value of JAVADOC from the environment. Use command line variables instead." >&2;}
+      fi
+      # Try to locate tool using the code snippet
+
+      { $as_echo "$as_me:${as_lineno-$LINENO}: checking for javadoc in Boot JDK" >&5
+$as_echo_n "checking for javadoc in Boot JDK... " >&6; }
+      JAVADOC=$BOOT_JDK/bin/javadoc
+      if test ! -x $JAVADOC; then
+        { $as_echo "$as_me:${as_lineno-$LINENO}: result: not found" >&5
+$as_echo "not found" >&6; }
+        { $as_echo "$as_me:${as_lineno-$LINENO}: Your Boot JDK seems broken. This might be fixed by explicitly setting --with-boot-jdk" >&5
+$as_echo "$as_me: Your Boot JDK seems broken. This might be fixed by explicitly setting --with-boot-jdk" >&6;}
+        as_fn_error $? "Could not find javadoc in the Boot JDK" "$LINENO" 5
+      fi
+      { $as_echo "$as_me:${as_lineno-$LINENO}: result: ok" >&5
+$as_echo "ok" >&6; }
+
+
+    else
+      # If it succeeded, then it was overridden by the user. We will use it
+      # for the tool.
+
+      # First remove it from the list of overridden variables, so we can test
+      # for unknown variables in the end.
+      CONFIGURE_OVERRIDDEN_VARIABLES="$try_remove_var"
+
+      # Check if we try to supply an empty value
+      if test "x$JAVADOC" = x; then
+        { $as_echo "$as_me:${as_lineno-$LINENO}: Setting user supplied tool JAVADOC= (no value)" >&5
+$as_echo "$as_me: Setting user supplied tool JAVADOC= (no value)" >&6;}
+        { $as_echo "$as_me:${as_lineno-$LINENO}: checking for JAVADOC" >&5
+$as_echo_n "checking for JAVADOC... " >&6; }
+        { $as_echo "$as_me:${as_lineno-$LINENO}: result: disabled" >&5
+$as_echo "disabled" >&6; }
+      else
+        # Check if the provided tool contains a complete path.
+        tool_specified="$JAVADOC"
+        tool_basename="${tool_specified##*/}"
+        if test "x$tool_basename" = "x$tool_specified"; then
+          # A command without a complete path is provided, search $PATH.
+          { $as_echo "$as_me:${as_lineno-$LINENO}: Will search for user supplied tool JAVADOC=$tool_basename" >&5
+$as_echo "$as_me: Will search for user supplied tool JAVADOC=$tool_basename" >&6;}
+          # Extract the first word of "$tool_basename", so it can be a program name with args.
+set dummy $tool_basename; ac_word=$2
+{ $as_echo "$as_me:${as_lineno-$LINENO}: checking for $ac_word" >&5
+$as_echo_n "checking for $ac_word... " >&6; }
+if ${ac_cv_path_JAVADOC+:} false; then :
+  $as_echo_n "(cached) " >&6
+else
+  case $JAVADOC in
+  [\\/]* | ?:[\\/]*)
+  ac_cv_path_JAVADOC="$JAVADOC" # Let the user override the test with a path.
+  ;;
+  *)
+  as_save_IFS=$IFS; IFS=$PATH_SEPARATOR
+for as_dir in $PATH
+do
+  IFS=$as_save_IFS
+  test -z "$as_dir" && as_dir=.
+    for ac_exec_ext in '' $ac_executable_extensions; do
+  if as_fn_executable_p "$as_dir/$ac_word$ac_exec_ext"; then
+    ac_cv_path_JAVADOC="$as_dir/$ac_word$ac_exec_ext"
+    $as_echo "$as_me:${as_lineno-$LINENO}: found $as_dir/$ac_word$ac_exec_ext" >&5
+    break 2
+  fi
+done
+  done
+IFS=$as_save_IFS
+
+  ;;
+esac
+fi
+JAVADOC=$ac_cv_path_JAVADOC
+if test -n "$JAVADOC"; then
+  { $as_echo "$as_me:${as_lineno-$LINENO}: result: $JAVADOC" >&5
+$as_echo "$JAVADOC" >&6; }
+else
+  { $as_echo "$as_me:${as_lineno-$LINENO}: result: no" >&5
+$as_echo "no" >&6; }
+fi
+
+
+          if test "x$JAVADOC" = x; then
+            as_fn_error $? "User supplied tool $tool_basename could not be found" "$LINENO" 5
+          fi
+        else
+          # Otherwise we believe it is a complete path. Use it as it is.
+          { $as_echo "$as_me:${as_lineno-$LINENO}: Will use user supplied tool JAVADOC=$tool_specified" >&5
+$as_echo "$as_me: Will use user supplied tool JAVADOC=$tool_specified" >&6;}
+          { $as_echo "$as_me:${as_lineno-$LINENO}: checking for JAVADOC" >&5
+$as_echo_n "checking for JAVADOC... " >&6; }
+          if test ! -x "$tool_specified"; then
+            { $as_echo "$as_me:${as_lineno-$LINENO}: result: not found" >&5
+$as_echo "not found" >&6; }
+            as_fn_error $? "User supplied tool JAVADOC=$tool_specified does not exist or is not executable" "$LINENO" 5
+          fi
+          { $as_echo "$as_me:${as_lineno-$LINENO}: result: $tool_specified" >&5
+$as_echo "$tool_specified" >&6; }
+        fi
+      fi
+    fi
+
+  fi
+
+
+
+  # Use user overridden value if available, otherwise locate tool in the Boot JDK.
+
+  # Publish this variable in the help.
+
+
   if [ -z "${JAR+x}" ]; then
     # The variable is not set by user, try to locate tool using the code snippet
 
--- a/make/autoconf/spec.gmk.in	Sat Oct 21 00:06:31 2017 +0000
+++ b/make/autoconf/spec.gmk.in	Mon Oct 23 10:21:13 2017 +0200
@@ -532,6 +532,7 @@
 JAVA_CMD:=@JAVA@
 JAVAC_CMD:=@JAVAC@
 JAVAH_CMD:=@JAVAH@
+JAVADOC_CMD:=@JAVADOC@
 JAR_CMD:=@JAR@
 JLINK_CMD := @JLINK@
 JMOD_CMD := @JMOD@
@@ -544,6 +545,7 @@
 JAVA_JAVAC=@FIXPATH@ $(JAVA_CMD) $(JAVA_FLAGS_JAVAC) $(JAVA_FLAGS)
 JAVAC=@FIXPATH@ $(JAVAC_CMD)
 JAVAH=@FIXPATH@ $(JAVAH_CMD)
+JAVADOC=@FIXPATH@ $(JAVADOC_CMD)
 JAR=@FIXPATH@ $(JAR_CMD)
 JLINK = @FIXPATH@ $(JLINK_CMD) $(JAVA_TOOL_FLAGS_SMALL)
 JMOD = @FIXPATH@ $(JMOD_CMD) $(JAVA_TOOL_FLAGS_SMALL)