--- old/make/Docs.gmk 2017-10-19 14:25:15.620047686 +0200
+++ new/make/Docs.gmk 2017-10-19 14:25:15.360051824 +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
@@ -105,6 +110,12 @@
-serialwarn -encoding ISO-8859-1 -docencoding UTF-8 -breakiterator \
-splitIndex --system none -html5 -javafx --expand-requires transitive
+# 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
@@ -129,6 +140,11 @@
endif
DRAFT_TEXT := This specification is not final and is subject to change. \
Use is subject to license terms.
+
+ # Workaround stylesheet bug
+ HEADER_STYLE := style="margin-top: 9px;"
+else
+ HEADER_STYLE := style="margin-top: 14px;"
endif
JAVADOC_BOTTOM := \
@@ -147,12 +163,19 @@
documentation redistribution policy. \
$(DRAFT_MARKER_STR)
-
JAVADOC_TOP := \
$$($1_SHORT_NAME) \
+ $1_DOC_TITLE := $$($1_LONG_NAME)
Version $$(VERSION_SPECIFICATION) API \
+ Specification
+ $1_WINDOW_TITLE := $$(subst &,&,$$($1_SHORT_NAME)) $$(DRAFT_MARKER_TITLE)
+ $1_HEADER_TITLE :=
$$($1_SHORT_NAME) \
$$(DRAFT_MARKER_STR)
$1_OPTIONS += -doctitle '$$($1_DOC_TITLE)'
@@ -302,8 +326,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)
@@ -319,9 +348,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
@@ -431,18 +459,29 @@
# 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 := \
- \
- \
- \
-
\
- \
-
+$(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)
@@ -553,6 +592,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)
@@ -560,8 +603,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