--- 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 &,&,$$($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 &,&,$$($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)