8189056: javadoc target for stable specdiff comparisons

Reviewed-by: erikj

8189056: javadoc target for stable specdiff comparisons
Reviewed-by: erikj
b48c2c3a · ihse · 45821aef · b48c2c3a · b48c2c3a · b48c2c3a
5 changed file
--- 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,6 +593,10 @@ 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)
@@ -561,8 +604,10 @@ 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
--- 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

--- 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)


--- a/make/autoconf/generated-configure.sh
+++ b/make/autoconf/generated-configure.sh
@@ -881,6 +881,7 @@ JAVAC_FLAGS
 BOOT_JDK_SOURCETARGET
 JARSIGNER
 JAR
+JAVADOC
 JAVAH
 JAVAC
 JAVA
@@ -1294,6 +1295,7 @@ PKG_CONFIG
 JAVA
 JAVAC
 JAVAH
+JAVADOC
 JAR
 JARSIGNER
 CC
@@ -2237,6 +2239,7 @@ Some influential environment variables:
  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 @@ VS_SDK_PLATFORM_NAME_2013=
 #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

 ###############################################################################
 #
@@ -31169,6 +31172,144 @@ $as_echo "$tool_specified" >&6; }



+  # Use user overridden value if available, otherwise locate tool in the Boot JDK.
+
+  # 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.
--- a/make/autoconf/spec.gmk.in
+++ b/make/autoconf/spec.gmk.in
@@ -532,6 +532,7 @@ SJAVAC_SERVER_JAVA_FLAGS:=@SJAVAC_SERVER_JAVA_FLAGS@
 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_SMALL=@FIXPATH@ $(JAVA_CMD) $(JAVA_FLAGS_SMALL) $(JAVA_FLAGS)
 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)