--- a/make/Javadoc.gmk Wed Apr 19 10:24:42 2017 +0200
+++ b/make/Javadoc.gmk Wed Apr 19 10:44:40 2017 +0200
@@ -37,12 +37,9 @@
################################################################################
# Javadoc settings
-# All modules to have docs generated by docs-javadoc target
-JAVADOC_MODULES := $(sort $(DOCS_MODULES))
-
# On top of the sources that was used to compile the JDK, we need some
# extra java.rmi sources that are used just for javadoc.
-JAVADOC_SOURCE_PATH := $(call PathList, $(call GetModuleSrcPath) \
+MODULES_SOURCE_PATH := $(call PathList, $(call GetModuleSrcPath) \
$(SUPPORT_OUTPUTDIR)/rmic/* $(JDK_TOPDIR)/src/*/share/doc/stub)
# Should we use -Xdocrootparent? Allow custom to overwrite.
@@ -89,13 +86,6 @@
-serialwarn -encoding ISO-8859-1 -breakiterator -splitIndex --system none \
--expand-requires transitive
-#
-# TODO: this should be set by the configure option.
-#
-ifndef ENABLE_MODULE_GRAPH
- ENABLE_MODULE_GRAPH=false
-endif
-
# Should we add DRAFT stamps to the generated javadoc?
ifeq ($(VERSION_IS_GA), true)
IS_DRAFT := false
@@ -118,16 +108,9 @@
endif
endif
-
-################################################################################
-# JDK javadoc titles/text snippets
-
JAVADOC_WINDOW_TITLE := Java Platform SE $(VERSION_SPECIFICATION) \
$(DRAFT_MARKER_TITLE)
-JAVADOC_DOC_TITLE := Java™ Platform, Standard Edition Development Kit \
- (JDK™) $(VERSION_SPECIFICATION)<br>API Specification
-
JAVADOC_HEADER_TITLE := $(subst $(SPACE), ,$(strip \
<strong>Java™ Platform<br>Standard Ed. \
$(VERSION_SPECIFICATION)</strong>$(DRAFT_MARKER_STR)))
@@ -156,100 +139,208 @@
purpose of evaluation.</div></div>
################################################################################
-# Java SE Reference javadoc titles/text snippets
+# JDK javadoc titles/text snippets
+
+JDK_JAVADOC_DOC_TITLE := Java™ Platform, Standard Edition Development Kit \
+ (JDK™) $(VERSION_SPECIFICATION)<br>API Specification
-REFERENCE_DOC_TITLE := Java™ Platform, Standard Edition \
+################################################################################
+# Java SE javadoc titles/text snippets
+
+JAVASE_JAVADOC_DOC_TITLE := Java™ Platform, Standard Edition \
$(VERSION_SPECIFICATION)<br>API Specification
################################################################################
-# Setup call to JDK javadoc based on above settings
-
-# Create a string like "-Xdoclint:all,-syntax,-html,..."
-JAVADOC_OPTIONS += -Xdoclint:all,$(call CommaList, $(addprefix -, \
- $(JAVADOC_DISABLED_DOCLINT)))
-
-ifneq ($($DOCROOTPARENT_FLAG), )
- JAVADOC_OPTIONS += -Xdocrootparent $(JAVADOC_BASE_URL)
-endif
-
-JAVADOC_TITLE_OPTIONS += -doctitle '$(JAVADOC_DOC_TITLE)'
-JAVADOC_TITLE_OPTIONS += -windowtitle '$(JAVADOC_WINDOW_TITLE)'
-JAVADOC_TITLE_OPTIONS += -header '$(JAVADOC_HEADER_TITLE)'
-JAVADOC_TITLE_OPTIONS += -bottom '$(JAVADOC_BOTTOM)'
-ifeq ($(IS_DRAFT), true)
- JAVADOC_TITLE_OPTIONS += -top '$(JAVADOC_TOP)'
-endif
-
-# Do not store debug level options in VARDEPS.
-ifneq ($(LOG_LEVEL), trace)
- JAVADOC_LOG_OPTION += -quiet
-else
- JAVADOC_LOG_OPTION += -verbose
-endif
+# Functions
-JAVADOC_VARDEPS := $(JAVADOC_OPTIONS) $(JAVADOC_TITLE_OPTIONS) $(JAVADOC_TAGS) \
- $(JAVADOC_MODULES) $(JAVADOC_SOURCE_PATH)
-JAVADOC_VARDEPS_FILE := $(call DependOnVariable, JAVADOC_VARDEPS, \
- $(SUPPORT_OUTPUTDIR)/docs/javadoc.vardeps)
-
-# Get a list of all files in all the source dirs for all included modules
-JAVADOC_SOURCE_DEPS := $(call CacheFind, $(wildcard \
- $(foreach module, $(JAVADOC_MODULES), $(call FindModuleSrcDirs, $(module)))))
-
-JAVADOC_TARGET_DIR := $(JAVADOC_OUTPUTDIR)/api
-JAVADOC_OVERVIEW := $(JDK_TOPDIR)/src/java.base/share/classes/overview-core.html
+# Helper function for creating a png file from a dot file generated by the
+# GenGraphs tool.
+# param 1: SetupJavadocGeneration namespace ($1)
+# param 2: module name
+#
+define setup_gengraph_dot_to_png
+ $1_$2_DOT_SRC := $$($1_GENGRAPHS_DIR)/$2.dot
+ $1_$2_PNG_TARGET := $$($1_TARGET_DIR)/$2-graph.png
-# Javadoc creates a lot of files but use index.html as a marker
-$(JAVADOC_TARGET_DIR)/index.html: $(BUILD_TOOLS_JDK) $(JAVADOC_VARDEPS_FILE) \
- $(JAVADOC_SOURCE_DEPS) $(JAVADOC_OVERVIEW)
- $(call LogWarn, Generating Javadoc for $(words $(JAVADOC_MODULES)) modules)
- $(call LogInfo, Javadoc modules: $(JAVADOC_MODULES))
- $(call MakeDir, $(JAVADOC_TARGET_DIR))
- $(call ExecuteWithLog, $(SUPPORT_OUTPUTDIR)/docs/javadoc, \
- $(JAVA) -Djava.awt.headless=true \
- -DenableModuleGraph=$(ENABLE_MODULE_GRAPH) \
- $(NEW_JAVADOC) -d $(JAVADOC_TARGET_DIR) \
- $(JAVADOC_TAGS) $(JAVADOC_OPTIONS) $(JAVADOC_LOG_OPTION) \
- $(JAVADOC_TITLE_OPTIONS) -overview $(JAVADOC_OVERVIEW) \
- --module-source-path $(JAVADOC_SOURCE_PATH) \
- --module $(call CommaList, $(JAVADOC_MODULES)))
+ # For each module needing a graph, create a png file from the dot file
+ # generated by the GenGraphs tool and store it in the target dir.
+ $$($1_$2_PNG_TARGET): $$($1_GENGRAPHS_MARKER)
+ $$(call MakeDir, $$(@D))
+ $$(call ExecuteWithLog, $$($1_$2_DOT_SRC), \
+ $$(DOT) -Tpng -o $$($1_$2_PNG_TARGET) $$($1_$2_DOT_SRC))
-JAVADOC_TARGETS += $(JAVADOC_TARGET_DIR)/index.html
+ $1_MODULEGRAPH_TARGETS += $$($1_$2_PNG_TARGET)
+endef
################################################################################
-# Setup call to Java SE Reference javadoc based on above settings
+# Setup make rules for creating the API documentation, using javadoc and other
+# tools if needed.
+#
+# Parameter 1 is the name of the rule. This name is used as variable prefix.
+# Targets generated are returned as $1_JAVADOC_TARGETS and
+# $1_MODULEGRAPH_TARGETS. Note that the index.html file will work as a "touch
+# file" for all the magnitude of files that are generated by javadoc.
+#
+# Remaining parameters are named arguments. These include:
+# MODULES - Modules to generate javadoc for
+# NAME - The name of the javadoc compilation, to be presented to the user
+# TARGET_DIR - Where to store the output
+# OVERVIEW - Path to an html overview file
+# DOC_TITLE - Title to use in -doctitle.
+# WINDOW_TITLE - Title to use in -windowtitle.
+# HEADER_TITLE - Title to use in -header.
+# BOTTOM_TEXT - Text to use in -bottom.
+# TOP_TEXT - Text to use in -top.
+#
+SetupApiDocsGeneration = $(NamedParamsMacroTemplate)
+define SetupApiDocsGenerationBody
-REFERENCE_TARGET_DIR := $(IMAGES_OUTPUTDIR)/javase-docs/api
-REFERENCE_OVERVIEW := $(JDK_TOPDIR)/src/java.base/share/classes/overview-core.html
+ # Figure out all modules, both specified and transitive, that will be processed
+ # by javadoc.
+ $1_TRANSITIVE_MODULES := $$(call FindTransitiveDepsForModules, $$($1_MODULES))
+ $1_ALL_MODULES := $$(sort $$($1_MODULES) $$($1_TRANSITIVE_MODULES))
+
+ ifeq ($$(ENABLE_FULL_DOCS), true)
+ # Tell the ModuleGraph taglet to generate html links to soon-to-be-created
+ # png files with module graphs.
+ $1_JAVA_ARGS += -DenableModuleGraph=true
+ endif
+
+ # Always include tags and basic options
+ $1_OPTIONS := $$(JAVADOC_TAGS) $$(JAVADOC_OPTIONS)
+
+ $1_OPTIONS += -overview $$($1_OVERVIEW)
+ $1_OPTIONS += --module-source-path $$(MODULES_SOURCE_PATH)
+ $1_OPTIONS += --module $$(call CommaList, $$($1_MODULES))
-REFERENCE_TITLE_OPTIONS += -doctitle '$(REFERENCE_DOC_TITLE)'
-REFERENCE_TITLE_OPTIONS += -windowtitle '$(JAVADOC_WINDOW_TITLE)'
-REFERENCE_TITLE_OPTIONS += -header '$(JAVADOC_HEADER_TITLE)'
-REFERENCE_TITLE_OPTIONS += -bottom '$(JAVADOC_BOTTOM)'
-ifeq ($(IS_DRAFT), true)
- REFERENCE_TITLE_OPTIONS += -top '$(JAVADOC_TOP)'
-endif
+ # Create a string like "-Xdoclint:all,-syntax,-html,..."
+ $1_OPTIONS += -Xdoclint:all,$$(call CommaList, $$(addprefix -, \
+ $$(JAVADOC_DISABLED_DOCLINT)))
+
+ ifneq ($$($$DOCROOTPARENT_FLAG), )
+ $1_OPTIONS += -Xdocrootparent $$(JAVADOC_BASE_URL)
+ endif
+
+ $1_OPTIONS += -doctitle '$$($1_DOC_TITLE)'
+ $1_OPTIONS += -windowtitle '$$($1_WINDOW_TITLE)'
+ $1_OPTIONS += -header '$$($1_HEADER_TITLE)'
+ $1_OPTIONS += -bottom '$$($1_BOTTOM_TEXT)'
+ ifeq ($$(IS_DRAFT), true)
+ $1_OPTIONS += -top '$$($1_TOP_TEXT)'
+ endif
+
+ # Do not store debug level options in VARDEPS.
+ ifneq ($$(LOG_LEVEL), trace)
+ $1_LOG_OPTION += -quiet
+ else
+ $1_LOG_OPTION += -verbose
+ endif
+
+ $1_VARDEPS := $$($1_JAVA_ARGS) $$($1_OPTIONS) $$(MODULES_SOURCE_PATH) \
+ $$($1_ALL_MODULES)
+ $1_VARDEPS_FILE := $$(call DependOnVariable, $1_VARDEPS, \
+ $$(SUPPORT_OUTPUTDIR)/docs/$1.vardeps)
+
+ # Get a list of all files in all the source dirs for all included modules
+ $1_SOURCE_DEPS := $$(call CacheFind, $$(wildcard $$(foreach module, \
+ $$($1_ALL_MODULES), $$(call FindModuleSrcDirs, $$(module)))))
+
+ # Javadoc creates a lot of files but use index.html as a marker
+ $$($1_TARGET_DIR)/index.html: $$(BUILD_TOOLS_JDK) $$($1_VARDEPS_FILE) \
+ $$($1_SOURCE_DEPS) $$($1_OVERVIEW)
+ $$(call LogWarn, Generating $$($1_NAME) API javadoc for \
+ $$(words $$($1_ALL_MODULES)) modules)
+ $$(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))
-REFERENCE_VARDEPS := $(JAVADOC_OPTIONS) $(REFERENCE_TITLE_OPTIONS) $(JAVADOC_TAGS) \
- $(JAVADOC_MODULES) $(JAVADOC_SOURCE_PATH)
-REFERENCE_VARDEPS_FILE := $(call DependOnVariable, REFERENCE_VARDEPS, \
- $(SUPPORT_OUTPUTDIR)/docs/reference.vardeps)
+ $1_JAVADOC_TARGETS := $$($1_TARGET_DIR)/index.html
+
+ ifeq ($$(ENABLE_FULL_DOCS), true)
+ # We have asked ModuleGraph to generate links to png files. Now we must
+ # produce the png files.
+
+ # Locate which modules has the @moduleGraph tag in their module-info.java
+ $1_MODULES_NEEDING_GRAPH := $$(strip $$(foreach m, $$($1_ALL_MODULES), \
+ $$(if $$(shell $$(GREP) -e @moduleGraph \
+ $$(wildcard $$(addsuffix /module-info.java, \
+ $$(call FindModuleSrcDirs, $$m)))), \
+ $$m) \
+ ))
+
+ # First we run the GenGraph tool. It will query the module structure of the
+ # running JVM and output .dot files for all existing modules.
+ GENGRAPHS_PROPS := \
+ $$(JDK_TOPDIR)/make/src/classes/build/tools/jigsaw/javadoc-graphs.properties
+
+ $1_GENGRAPHS_DIR := $$(SUPPORT_OUTPUTDIR)/docs/$1-gengraphs
+ $1_GENGRAPHS_MARKER := $$($1_GENGRAPHS_DIR)/_gengraphs_run.marker
+
+ $$($1_GENGRAPHS_MARKER): $$(BUILD_JIGSAW_TOOLS) $$(GENGRAPHS_PROPS)
+ $$(call LogInfo, Running gengraphs for $$($1_NAME) API documentation)
+ $$(call MakeDir, $$($1_GENGRAPHS_DIR))
+ $$(call ExecuteWithLog, $$($1_GENGRAPHS_DIR)/gengraphs, \
+ $$(TOOL_GENGRAPHS) --spec --output $$($1_GENGRAPHS_DIR) \
+ --dot-attributes $$(GENGRAPHS_PROPS) && \
+ $$(TOUCH) $$($1_GENGRAPHS_MARKER))
+
+ # For each module needing a graph, create a png file from the dot file
+ # generated by the GenGraphs tool and store it in the target dir.
+ # They will depend on $1_GENGRAPHS_MARKER, and will be added to $1.
+ $$(foreach m, $$($1_MODULES_NEEDING_GRAPH), \
+ $$(eval $$(call setup_gengraph_dot_to_png,$1,$$m)) \
+ )
+ endif
+endef
+
+################################################################################
+# Setup generation of the JDK API documentation (javadoc + modulegraph)
-# Javadoc creates a lot of files but use index.html as a marker.
-$(REFERENCE_TARGET_DIR)/index.html: $(BUILD_TOOLS_JDK) $(REFERENCE_VARDEPS_FILE) \
- $(JAVADOC_SOURCE_DEPS) $(REFERENCE_OVERVIEW)
- $(call LogWarn, Generating reference Javadoc for Java SE)
- $(call MakeDir, $(REFERENCE_TARGET_DIR))
- $(call ExecuteWithLog, $(SUPPORT_OUTPUTDIR)/docs/reference, \
- $(JAVA) -Djava.awt.headless=true \
- -DenableModuleGraph=$(ENABLE_MODULE_GRAPH) \
- $(NEW_JAVADOC) -d $(REFERENCE_TARGET_DIR) \
- $(JAVADOC_TAGS) $(JAVADOC_OPTIONS) $(JAVADOC_LOG_OPTION) \
- $(REFERENCE_TITLE_OPTIONS) -overview $(REFERENCE_OVERVIEW) \
- --module-source-path $(JAVADOC_SOURCE_PATH) \
- --module java.se.ee)
+# All modules to have docs generated by docs-jdk-api target
+JDK_JAVADOC_MODULES := $(sort $(DOCS_MODULES))
+
+JDK_JAVADOC_OVERVIEW := $(JDK_TOPDIR)/src/java.base/share/classes/overview-core.html
+
+$(eval $(call SetupApiDocsGeneration, JDK_API, \
+ MODULES := $(JDK_JAVADOC_MODULES), \
+ NAME := JDK, \
+ TARGET_DIR := $(JAVADOC_OUTPUTDIR)/api, \
+ OVERVIEW := $(JDK_JAVADOC_OVERVIEW), \
+ DOC_TITLE := $(JDK_JAVADOC_DOC_TITLE), \
+ WINDOW_TITLE := $(JAVADOC_WINDOW_TITLE), \
+ HEADER_TITLE := $(JAVADOC_HEADER_TITLE), \
+ BOTTOM_TEXT := $(JAVADOC_BOTTOM), \
+ TOP_TEXT := $(JAVADOC_TOP), \
+))
+
+# Targets generated are returned in JDK_API_JAVADOC_TARGETS and
+# JDK_API_MODULEGRAPH_TARGETS.
-REFERENCE_TARGETS += $(REFERENCE_TARGET_DIR)/index.html
+################################################################################
+# Setup generation of the Java SE API documentation (javadoc + modulegraph)
+
+# The Java SE module scope is just java.se.ee and it's transitive modules.
+JAVASE_JAVADOC_MODULES := java.se.ee
+
+JAVASE_JAVADOC_OVERVIEW := $(JDK_TOPDIR)/src/java.base/share/classes/overview-core.html
+
+$(eval $(call SetupApiDocsGeneration, JAVASE_API, \
+ MODULES := $(JAVASE_JAVADOC_MODULES), \
+ NAME := Java SE, \
+ TARGET_DIR := $(IMAGES_OUTPUTDIR)/javase-docs/api, \
+ OVERVIEW := $(JAVASE_JAVADOC_OVERVIEW), \
+ DOC_TITLE := $(JAVASE_JAVADOC_DOC_TITLE), \
+ WINDOW_TITLE := $(JAVADOC_WINDOW_TITLE), \
+ HEADER_TITLE := $(JAVADOC_HEADER_TITLE), \
+ BOTTOM_TEXT := $(JAVADOC_BOTTOM), \
+ TOP_TEXT := $(JAVADOC_TOP), \
+))
+
+# Targets generated are returned in JAVASE_API_JAVADOC_TARGETS and
+# JAVASE_API_MODULEGRAPH_TARGETS.
################################################################################
# Copy targets
@@ -283,42 +374,33 @@
$(eval $(call SetupZipArchive, BUILD_JAVADOC_ZIP, \
SRC := $(JAVADOC_OUTPUTDIR), \
ZIP := $(JAVADOC_ZIP_FILE), \
- EXTRA_DEPS := $(JAVADOC_TARGETS) $(COPY_TARGETS), \
+ EXTRA_DEPS := $(JDK_API_JAVADOC_TARGETS) $(JDK_API_MODULEGRAPH_TARGETS) \
+ $(COPY_TARGETS), \
))
ZIP_TARGETS += $(BUILD_JAVADOC_ZIP)
################################################################################
-# generate .dot files for module graphs
-
-JAVADOC_MODULE_GRAPHS_DIR := $(SUPPORT_OUTPUTDIR)/docs/module-graphs
-JAVADOC_MODULE_GRAPHS := $(JAVADOC_MODULE_GRAPHS_DIR)/java.se.dot
-JAVADOC_MODULE_GRAPHS_PROPS := $(JDK_TOPDIR)/make/src/classes/build/tools/jigsaw/javadoc-graphs.properties
-
-$(JAVADOC_MODULE_GRAPHS): $(BUILD_JIGSAW_TOOLS) $(JAVADOC_MODULE_GRAPHS_PROPS)
- $(MKDIR) -p $(@D)
- $(TOOL_GENGRAPHS) --spec --output $(JAVADOC_MODULE_GRAPHS_DIR) \
- --dot-attributes $(JAVADOC_MODULE_GRAPHS_PROPS)
-
-MODULE_GRAPH_TARGETS += $(JAVADOC_MODULE_GRAPHS)
-
-################################################################################
# Hook to include the corresponding custom file, if present.
$(eval $(call IncludeCustomExtension, , Javadoc.gmk))
################################################################################
-docs-module-graphs: $(MODULE_GRAPH_TARGETS)
+docs-jdk-api-javadoc: $(JDK_API_JAVADOC_TARGETS)
+
+docs-jdk-api-modulegraph: $(JDK_API_MODULEGRAPH_TARGETS)
-docs-javadoc: $(JAVADOC_TARGETS)
+docs-javase-api-javadoc: $(JAVASE_API_JAVADOC_TARGETS)
-docs-reference: $(REFERENCE_TARGETS)
+docs-javase-api-modulegraph: $(JAVASE_API_MODULEGRAPH_TARGETS)
docs-copy: $(COPY_TARGETS)
docs-zip: $(ZIP_TARGETS)
-all: docs-module-graphs docs-javadoc docs-reference docs-copy docs-zip
+all: docs-jdk-api-javadoc docs-jdk-api-modulegraph docs-javase-api-javadoc \
+ docs-javase-api-modulegraph docs-copy docs-zip
-.PHONY: default all docs-module-graphs docs-javadoc docs-reference docs-copy docs-zip
+.PHONY: default all docs-jdk-api-javadoc docs-jdk-api-modulegraph \
+ docs-javase-api-javadoc docs-javase-api-modulegraph docs-copy docs-zip
--- a/make/common/Modules.gmk Wed Apr 19 10:24:42 2017 +0200
+++ b/make/common/Modules.gmk Wed Apr 19 10:44:40 2017 +0200
@@ -294,15 +294,15 @@
( $(PRINTF) "DEPS_$(call GetModuleNameFromModuleInfo, $m) :=" && \
$(NAWK) -v MODULE=$(call GetModuleNameFromModuleInfo, $m) '\
BEGIN { if (MODULE != "java.base") printf(" java.base"); } \
- /requires/ { sub(/;/, ""); \
- sub(/requires/, ""); \
- sub(/transitive/, ""); \
- sub(/\/\/.*/, ""); \
- sub(/\/\*.*\*\//, ""); \
- gsub(/^ +\*.*/, ""); \
- gsub(/ /, ""); \
- printf(" %s", $$0) } \
- END { printf("\n") }' $m \
+ /^ *requires/ { sub(/;/, ""); \
+ sub(/requires/, ""); \
+ sub(/transitive/, ""); \
+ sub(/\/\/.*/, ""); \
+ sub(/\/\*.*\*\//, ""); \
+ gsub(/^ +\*.*/, ""); \
+ gsub(/ /, ""); \
+ printf(" %s", $$0) } \
+ END { printf("\n") }' $m \
) >> $@ $(NEWLINE))
-include $(MODULE_DEPS_MAKEFILE)
@@ -320,6 +320,11 @@
$(foreach n, $(call FindDepsForModule, $m), \
$(call FindDepsForModule, $n))))
+# Finds transitive dependencies in 3 levels for a set of modules.
+# Param 1: List of modules to find transitive deps for
+FindTransitiveDepsForModules = \
+ $(sort $(foreach m, $1, $(call FindTransitiveDepsForModule, $m)))
+
# Upgradeable modules are those that are either defined as upgradeable or that
# require an upradeable module.
FindAllUpgradeableModules = \