--- 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 := \
$(DRAFT_TEXT)
+JDK_INDEX_CONTENT := \ + \ + \ + \ + \ + \ + + ################################################################################ # JDK javadoc titles/text snippets @@ -257,8 +280,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)) @@ -267,15 +296,10 @@ $1_OPTIONS += -Xdoclint:all,$$(call CommaList, $$(addprefix -, \ $$(JAVADOC_DISABLED_DOCLINT))) - $1_DOC_TITLE := $$($1_LONG_NAME)
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 :=
$$($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