diff --git a/make/Javadoc.gmk b/make/Javadoc.gmk index e8c58ab6e18..28a7046d054 100644 --- a/make/Javadoc.gmk +++ b/make/Javadoc.gmk @@ -26,28 +26,24 @@ default: all include $(SPEC) include MakeBase.gmk +include Modules.gmk +include ZipArchive.gmk include $(JDK_TOPDIR)/make/Tools.gmk include $(JDK_TOPDIR)/make/ModuleTools.gmk -################################################################################ +# This is needed to properly setup DOCS_MODULES. +$(eval $(call ReadImportMetaData)) -# List of all possible directories for javadoc to look for sources -# Allow custom to overwrite. -JAVADOC_SOURCE_DIRS = \ - $(SUPPORT_OUTPUTDIR)/gensrc/* \ - $(addsuffix /*, $(IMPORT_MODULES_SRC)) \ - $(JDK_TOPDIR)/src/*/$(OPENJDK_TARGET_OS)/classes \ - $(JDK_TOPDIR)/src/*/$(OPENJDK_TARGET_OS_TYPE)/classes \ - $(JDK_TOPDIR)/src/*/share/classes \ - $(HOTSPOT_TOPDIR)/src/*/share/classes \ - $(LANGTOOLS_TOPDIR)/src/*/share/classes \ - $(NASHORN_TOPDIR)/src/*/share/classes \ - $(CORBA_TOPDIR)/src/*/share/classes \ - $(JAXP_TOPDIR)/src/*/share/classes \ - $(JAXWS_TOPDIR)/src/*/share/classes \ - $(SUPPORT_OUTPUTDIR)/rmic/* \ - $(JDK_TOPDIR)/src/*/share/doc/stub \ - # +################################################################################ +# 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) \ + $(SUPPORT_OUTPUTDIR)/rmic/* $(JDK_TOPDIR)/src/*/share/doc/stub) # Should we use -Xdocrootparent? Allow custom to overwrite. DOCROOTPARENT_FLAG = TRUE @@ -55,113 +51,11 @@ DOCROOTPARENT_FLAG = TRUE # URLs JAVADOC_BASE_URL := http://docs.oracle.com/javase/$(VERSION_SPECIFICATION)/docs BUG_SUBMIT_URL := http://bugreport.java.com/bugreport/ - -################################################################################ -# Text snippets - -FULL_COMPANY_NAME := Oracle and/or its affiliates -COMPANY_ADDRESS := 500 Oracle Parkway
Redwood Shores, CA 94065 USA -BUG_SUBMIT_LINE := Submit a bug or feature - -COMMON_BOTTOM_TEXT := $(BUG_SUBMIT_LINE)
Java is a trademark or registered \ - trademark of $(FULL_COMPANY_NAME) in the US and other countries. - -CORE_BOTTOM_COPYRIGHT_URL := {@docroot}/../legal/cpyr.html -CORE_BOTTOM_TEXT := \ - $(BUG_SUBMIT_LINE) \ -
For further API reference and developer documentation, see \ - Java SE \ - Documentation. That documentation contains more detailed, \ - developer-targeted descriptions, with conceptual overviews, definitions of \ - terms, workarounds, and working code examples. - -ifeq ($(VERSION_IS_GA), true) - DRAFT_MARKER := - DRAFT_WINDOW_TITLE_MARKER := - EARLYACCESS_TOP := -else - # We need a draft format when not building the GA version. - DRAFT_MARKER :=
DRAFT $(VERSION_STRING) - ifeq ($(VERSION_BUILD), 0) - DRAFT_WINDOW_TITLE_MARKER := $(SPACE)[ad-hoc build] - else - DRAFT_WINDOW_TITLE_MARKER := $(SPACE)[build $(VERSION_BUILD)] - endif - EARLYACCESS_TOP := \ -
Please note that the specifications \ - and other information contained herein are not final and are subject to \ - change. The information is being made available to you solely for \ - purpose of evaluation.
-endif - -################################################################################ -# Special treatment for the core package list. All separate "small" javadoc -# invocation needs to be able to see the core package list. - -ALL_PKG_DIRS := $(dir $(filter %.java, $(call CacheFind, \ - $(wildcard $(JAVADOC_SOURCE_DIRS))))) -ALL_SRC_PREFIXES := $(addsuffix /%, $(wildcard $(JAVADOC_SOURCE_DIRS))) -ALL_PKG_DIRNAMES := $(foreach prefix, $(ALL_SRC_PREFIXES), \ - $(patsubst $(prefix),%, $(filter $(prefix), $(ALL_PKG_DIRS)))) -ALL_PACKAGES := $(sort $(subst /,., $(patsubst %/, %, $(ALL_PKG_DIRNAMES)))) - -# Core packages are all packages beginning with java, javax or org, except a few -# excludes. -JAVA_PACKAGES := $(filter java.%, $(ALL_PACKAGES)) -JAVAX_PACKAGES := $(filter javax.%, $(ALL_PACKAGES)) -ORG_PACKAGES := $(filter org.%, $(ALL_PACKAGES)) - -# Allow custom makefile to add more excluded packages -CORE_EXCLUDED_PACKAGES += \ - java.awt.dnd.peer \ - java.awt.peer \ - javax.smartcardio \ - org.jcp.xml.dsig.internal% \ - org.w3c.dom.css \ - org.w3c.dom.html \ - org.w3c.dom.stylesheets \ - org.w3c.dom.xpath \ - org.graalvm.compiler.% \ - # - -CORE_PACKAGES := $(filter-out $(CORE_EXCLUDED_PACKAGES), \ - $(JAVA_PACKAGES) $(JAVAX_PACKAGES) $(ORG_PACKAGES)) - -CORE_PACKAGES_LIST_DIR := $(SUPPORT_OUTPUTDIR)/docs/core-packages -CORE_PACKAGES_LIST_FILE := $(CORE_PACKAGES_LIST_DIR)/package-list - -CORE_PACKAGES_VARDEPS_FILE := $(call DependOnVariable, CORE_PACKAGES, \ - $(CORE_PACKAGES_LIST_FILE).vardeps) - -$(CORE_PACKAGES_LIST_FILE): $(CORE_PACKAGES_VARDEPS_FILE) - $(call MakeDir, $(@D)) - $(eval $(call ListPathsSafely, CORE_PACKAGES, $@)) - -################################################################################ -# Support functions for SetupJavadocGeneration - -# Generate the text used in the -bottom argument. -# Note that COPYRIGHT_YEAR is the current year (from spec.gmk) -# Arguments: -# arg 1: first copyright year -# arg 2: copyright url (optional) -# arg 3: free-form text snippet (optional) -define GenerateBottom - $(if $(strip $3), $(strip $3))
$(if \ - $(strip $2),Copyright,Copyright) \ - © $(strip $1), $(COPYRIGHT_YEAR), $(FULL_COMPANY_NAME). \ - $(COMPANY_ADDRESS). All rights reserved. -endef - -# Speed up finding by filling cache -$(eval $(call FillCacheFind, $(wildcard $(JAVADOC_SOURCE_DIRS)))) +COPYRIGHT_URL := {@docroot}/../legal/cpyr.html # In order to get a specific ordering it's necessary to specify the total # ordering of tags as the tags are otherwise ordered in order of definition. -DEFAULT_JAVADOC_TAGS := \ +JAVADOC_TAGS := \ -tag beaninfo:X \ -tag revised:X \ -tag since.unbundled:X \ @@ -187,8 +81,13 @@ DEFAULT_JAVADOC_TAGS := \ -tagletpath $(BUILDTOOLS_OUTPUTDIR)/jdk_tools_classes \ # -DEFAULT_JAVADOC_OPTIONS := -XDignore.symbol.file=true -use -keywords -notimestamp \ - -serialwarn -encoding ISO-8859-1 -breakiterator --system none +# Which doclint checks to ignore +JAVADOC_DISABLED_DOCLINT := accessibility html missing syntax reference + +# The initial set of options for javadoc +JAVADOC_OPTIONS := -XDignore.symbol.file=true -use -keywords -notimestamp \ + -serialwarn -encoding ISO-8859-1 -breakiterator -splitIndex --system none \ + --expand-requires transitive # # TODO: this should be set by the configure option. @@ -197,504 +96,163 @@ 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 +else + IS_DRAFT := true +endif + ################################################################################ -# Setup make rules for running javadoc. -# -# Parameter 1 is the name of the rule. This name is used as variable prefix, -# and the targets generated are listed in a variable by that name. 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 include -# PACKAGES - Packages to include -# IS_CORE - Set to TRUE for the Core API package which needs special treatment -# API_ROOT - Where to base the documentation (jre or jdk) -# DEST_DIR - A directory relative to the API root -# OVERVIEW - Path to a html overview file -# TITLE - Default title to use for the more specific versions below -# WINDOW_TITLE - Title to use in -windowtitle. Computed from TITLE if empty. -# HEADER_TITLE - Title to use in -header. Computed from TITLE if empty. -# DOC_TITLE - Title to use in -doctitle. Computed from TITLE if empty. -# FIRST_COPYRIGHT_YEAR - First year this bundle was introduced -# DISABLED_DOCLINT - Doclint warnings to exclude. -# DOCLINT_PACKAGES - Optional -Xdoclint/package value -# SPLIT_INDEX - Enable -splitIndex (split index-all.html if it is too large) -# BOTTOM_COPYRIGHT_URL - Copyright URL to use in -bottom -# BOTTOM_TEXT - Extra text to use in -bottom -# EXTRA_TOP - Additional -top data -# -SetupJavadocGeneration = $(NamedParamsMacroTemplate) -define SetupJavadocGenerationBody - ifeq ($$($1_IS_CORE), TRUE) - $1_JAVA := $$(JAVA) - $1_OUTPUT_DIRNAME := api +# General text snippets + +FULL_COMPANY_NAME := Oracle and/or its affiliates +COMPANY_ADDRESS := 500 Oracle Parkway
Redwood Shores, CA 94065 USA + +ifeq ($(IS_DRAFT), true) + DRAFT_MARKER_STR :=
DRAFT $(VERSION_STRING) + ifeq ($(VERSION_BUILD), 0) + DRAFT_MARKER_TITLE := [ad-hoc build] else - $1_JAVA := $$(JAVA_SMALL) - $1_OUTPUT_DIRNAME := $$($1_API_ROOT)/api/$$($1_DEST_DIR) - - # Compute a relative path to core root. - # The non-core api javadocs need to be able to access the root of the core - # api directory, so for jdk/api or jre/api to get to the core api/ - # directory we would use this - $1_RELATIVE_CORE_DIR := $$(call DirToDotDot, $$($1_OUTPUT_DIRNAME))/api - - # We need to tell javadoc the directory in which to find the core package-list - $1_OPTIONS += -linkoffline $$($1_RELATIVE_CORE_DIR) $$(CORE_PACKAGES_LIST_DIR) - - $1_DEPS += $(CORE_PACKAGES_LIST_FILE) + DRAFT_MARKER_TITLE := [build $(VERSION_BUILD)] endif +endif - $1_OPTIONS += --add-modules $$(call CommaList, $$($1_MODULES)) - - ifneq ($$($1_DISABLED_DOCLINT), ) - # Create a string like ",-syntax,-html" - $1_DOCLINT_EXCEPTIONS := ,$$(call CommaList, $$(addprefix -, $$($1_DISABLED_DOCLINT))) - endif - $1_OPTIONS += -Xdoclint:all$$($1_DOCLINT_EXCEPTIONS) - - ifneq ($$($1_DOCLINT_PACKAGES), ) - $1_OPTIONS += -Xdoclint/package:$$(call CommaList, $$($1_DOCLINT_PACKAGES)) - endif - - ifeq ($$($1_DOC_TITLE), ) - $1_DOC_TITLE := $$($1_TITLE) - endif - $1_OPTIONS += -doctitle '$$($1_DOC_TITLE)' - - ifeq ($$($1_WINDOW_TITLE), ) - $1_WINDOW_TITLE := $$(strip $$(subst ™,, $$($1_TITLE))) - endif - $1_OPTIONS += -windowtitle '$$($1_WINDOW_TITLE)$$(DRAFT_WINDOW_TITLE_MARKER)' - - ifeq ($$($1_HEADER_TITLE), ) - $1_HEADER_TITLE := $$(strip $$(subst ™,, $$($1_TITLE))) - endif - $1_OPTIONS += -header '$$($1_HEADER_TITLE)$$(DRAFT_MARKER)' - - ifneq ($$($1_EXTRA_TOP), ) - $1_OPTIONS += -top '$$($1_EXTRA_TOP)' - endif - - ifeq ($$($1_BOTTOM_TEXT), ) - $1_BOTTOM_TEXT := $(COMMON_BOTTOM_TEXT) - endif - $1_BOTTOM := $$(call GenerateBottom, $$($1_FIRST_COPYRIGHT_YEAR), \ - $$($1_BOTTOM_COPYRIGHT_URL), $$($1_BOTTOM_TEXT)) - $1_OPTIONS += -bottom '$$($1_BOTTOM)$$(DRAFT_MARKER)' - - ifneq ($$($1_OVERVIEW), ) - $1_OPTIONS += -overview $$($1_OVERVIEW) - $1_DEPS += $$($1_OVERVIEW) - endif - - ifneq ($$($1_SPLIT_INDEX), ) - $1_OPTIONS += -splitIndex - endif - - ifneq ($$($DOCROOTPARENT_FLAG), ) - $1_OPTIONS += -Xdocrootparent $(JAVADOC_BASE_URL) - endif - - $1_VARDEPS := $$($1_OPTIONS) $$($1_PACKAGES) - $1_VARDEPS_FILE := $$(call DependOnVariable, $1_VARDEPS, \ - $$(SUPPORT_OUTPUTDIR)/docs/$1.vardeps) - - # Do not store debug level options in VARDEPS. - ifneq ($$(LOG_LEVEL), trace) - $1_OPTIONS += -quiet - else - $1_OPTIONS += -verbose - endif - - $1_PACKAGE_DEPS := $$(call CacheFind, $$(wildcard $$(foreach p, \ - $$(subst .,/,$$(strip $$($1_PACKAGES))), \ - $$(addsuffix /$$p, $$(wildcard $$(JAVADOC_SOURCE_DIRS)))))) - - # If there are many packages, use an @-file... - ifneq ($$(word 17, $$($1_PACKAGES)), ) - $1_PACKAGES_FILE := $$(SUPPORT_OUTPUTDIR)/docs/$1.packages - $1_PACKAGES_ARG := @$$($1_PACKAGES_FILE) - else - $1_PACKAGES_ARG := $$($1_PACKAGES) - endif - - # The index.html which is a marker for all the output from javadoc. - $1_INDEX_FILE := $$(JAVADOC_OUTPUTDIR)/$$($1_OUTPUT_DIRNAME)/index.html - - # Rule for actually running javadoc - $$($1_INDEX_FILE): $$(BUILD_TOOLS_JDK) $$($1_VARDEPS_FILE) $$($1_PACKAGE_DEPS) $$($1_DEPS) - $$(call LogWarn, Generating Javadoc from $$(words $$($1_PACKAGES)) package(s) for $$($1_OUTPUT_DIRNAME)) - $$(call MakeDir, $$(@D)) - ifneq ($$($1_PACKAGES_FILE), ) - $$(eval $$(call ListPathsSafely, $1_PACKAGES, $$($1_PACKAGES_FILE))) - endif - $$(call ExecuteWithLog, $$(SUPPORT_OUTPUTDIR)/docs/$1.javadoc, \ - $$($1_JAVA) -Djava.awt.headless=true -DenableModuleGraph=$(ENABLE_MODULE_GRAPH) \ - $(NEW_JAVADOC) -d $$(@D) \ - $$(DEFAULT_JAVADOC_TAGS) $$(DEFAULT_JAVADOC_OPTIONS) \ - --module-source-path $$(call PathList, $$(JAVADOC_SOURCE_DIRS)) \ - $$($1_OPTIONS) $$($1_PACKAGES_ARG)) - - # The output returned will be the index.html file - $1 := $$($1_INDEX_FILE) -endef ################################################################################ +# JDK javadoc titles/text snippets -$(eval $(call SetupJavadocGeneration, coredocs, \ - MODULES := java.se.ee, \ - PACKAGES := $(CORE_PACKAGES), \ - IS_CORE := TRUE, \ - OVERVIEW := $(JDK_TOPDIR)/src/java.base/share/classes/overview-core.html, \ - WINDOW_TITLE := Java Platform SE $(VERSION_SPECIFICATION), \ - HEADER_TITLE := Java™ Platform
Standard Ed. $(VERSION_SPECIFICATION), \ - DOC_TITLE := Java™ Platform$(COMMA) Standard Edition \ - $(VERSION_SPECIFICATION)
API Specification, \ - FIRST_COPYRIGHT_YEAR := 1993, \ - DISABLED_DOCLINT := accessibility html missing syntax, \ - DOCLINT_PACKAGES := -org.omg.* jdk.internal.logging.*, \ - SPLIT_INDEX := TRUE, \ - BOTTOM_COPYRIGHT_URL := $(CORE_BOTTOM_COPYRIGHT_URL), \ - BOTTOM_TEXT := $(CORE_BOTTOM_TEXT), \ - EXTRA_TOP := $(EARLYACCESS_TOP), \ -)) +JAVADOC_WINDOW_TITLE := Java Platform SE $(VERSION_SPECIFICATION) \ + $(DRAFT_MARKER_TITLE) -TARGETS += $(coredocs) +JAVADOC_DOC_TITLE := Java™ Platform, Standard Edition Development Kit \ + (JDK™) $(VERSION_SPECIFICATION)
API Specification + +JAVADOC_HEADER_TITLE := $(subst $(SPACE), ,$(strip \ + Java™ Platform
Standard Ed. \ + $(VERSION_SPECIFICATION)$(DRAFT_MARKER_STR))) + +JAVADOC_BOTTOM := \ + \ + Submit a bug or feature
\ + For further API reference and developer documentation, see \ + Java SE \ + Documentation. That documentation contains more detailed, \ + developer-targeted descriptions, with conceptual overviews, definitions \ + of terms, workarounds, and working code examples.
\ + Java is a trademark or registered trademark of $(FULL_COMPANY_NAME) in \ + the US and other countries.
\ + Copyright \ + © 1993, $(COPYRIGHT_YEAR), $(FULL_COMPANY_NAME). \ + $(COMPANY_ADDRESS). All rights reserved.$(DRAFT_MARKER_STR) + +JAVADOC_TOP := \ +
Please note that the specifications \ + and other information contained herein are not final and are subject to \ + change. The information is being made available to you solely for \ + purpose of evaluation.
################################################################################ +# Java SE Reference javadoc titles/text snippets -$(eval $(call SetupJavadocGeneration, docletapi, \ - MODULES := jdk.javadoc, \ - PACKAGES := \ - jdk.javadoc.doclet, \ - API_ROOT := jdk, \ - DEST_DIR := javadoc/doclet, \ - TITLE := Doclet API, \ - FIRST_COPYRIGHT_YEAR := 1993, \ -)) - -TARGETS += $(docletapi) +REFERENCE_DOC_TITLE := Java™ Platform, Standard Edition \ + $(VERSION_SPECIFICATION)
API Specification ################################################################################ +# Setup call to JDK javadoc based on above settings -$(eval $(call SetupJavadocGeneration, old-docletapi, \ - MODULES := jdk.javadoc, \ - PACKAGES := com.sun.javadoc, \ - API_ROOT := jdk, \ - DEST_DIR := javadoc/old/doclet, \ - TITLE := Doclet API, \ - FIRST_COPYRIGHT_YEAR := 1993, \ -)) +# Create a string like "-Xdoclint:all,-syntax,-html,..." +JAVADOC_OPTIONS += -Xdoclint:all,$(call CommaList, $(addprefix -, \ + $(JAVADOC_DISABLED_DOCLINT))) -TARGETS += $(old-docletapi) +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 + +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 + +# 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))) + +JAVADOC_TARGETS += $(JAVADOC_TARGET_DIR)/index.html ################################################################################ +# Setup call to Java SE Reference javadoc based on above settings -$(eval $(call SetupJavadocGeneration, tagletapi, \ - MODULES := jdk.javadoc, \ - PACKAGES := com.sun.tools.doclets, \ - API_ROOT := jdk, \ - DEST_DIR := javadoc/old/taglet, \ - TITLE := Taglet API, \ - FIRST_COPYRIGHT_YEAR := 1993, \ -)) +REFERENCE_TARGET_DIR := $(IMAGES_OUTPUTDIR)/javase-docs/api +REFERENCE_OVERVIEW := $(JDK_TOPDIR)/src/java.base/share/classes/overview-core.html -TARGETS += $(tagletapi) +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 + +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) + +# 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) + +REFERENCE_TARGETS += $(REFERENCE_TARGET_DIR)/index.html ################################################################################ - -$(eval $(call SetupJavadocGeneration, domapi, \ - MODULES := \ - java.xml \ - jdk.xml.dom, \ - PACKAGES := \ - org.w3c.dom \ - org.w3c.dom.bootstrap \ - org.w3c.dom.ls \ - org.w3c.dom.ranges \ - org.w3c.dom.traversal \ - org.w3c.dom.html \ - org.w3c.dom.stylesheets \ - org.w3c.dom.css \ - org.w3c.dom.events \ - org.w3c.dom.views, \ - API_ROOT := jre, \ - DEST_DIR := plugin/dom, \ - TITLE := Common DOM API, \ - FIRST_COPYRIGHT_YEAR := 2005, \ - DISABLED_DOCLINT := accessibility html missing, \ - SPLIT_INDEX := TRUE, \ -)) - -TARGETS += $(domapi) - -################################################################################ - -$(eval $(call SetupJavadocGeneration, jdi, \ - MODULES := jdk.jdi, \ - PACKAGES := \ - com.sun.jdi \ - com.sun.jdi.event \ - com.sun.jdi.request \ - com.sun.jdi.connect \ - com.sun.jdi.connect.spi, \ - API_ROOT := jdk, \ - DEST_DIR := jpda/jdi, \ - OVERVIEW := $(JDK_TOPDIR)/src/jdk.jdi/share/classes/jdi-overview.html, \ - TITLE := Java™ Debug Interface, \ - FIRST_COPYRIGHT_YEAR := 1999, \ - DISABLED_DOCLINT := accessibility missing syntax, \ - SPLIT_INDEX := TRUE, \ -)) - -TARGETS += $(jdi) - -################################################################################ - -$(eval $(call SetupJavadocGeneration, jaas, \ - MODULES := jdk.security.auth, \ - PACKAGES := \ - com.sun.security.auth \ - com.sun.security.auth.callback \ - com.sun.security.auth.login \ - com.sun.security.auth.module, \ - API_ROOT := jre, \ - DEST_DIR := security/jaas/spec, \ - OVERVIEW := $(JDK_TOPDIR)/src/jdk.security.auth/share/classes/jaas-overview.html, \ - TITLE := Java™ Authentication and Authorization Service, \ - FIRST_COPYRIGHT_YEAR := 1998, \ - DISABLED_DOCLINT := missing, \ -)) - -TARGETS += $(jaas) - -################################################################################ - -$(eval $(call SetupJavadocGeneration, jgss, \ - MODULES := jdk.security.jgss, \ - PACKAGES := com.sun.security.jgss, \ - API_ROOT := jre, \ - DEST_DIR := security/jgss/spec, \ - OVERVIEW := $(JDK_TOPDIR)/src/java.security.jgss/share/classes/jgss-overview.html, \ - TITLE := Java™ GSS-API Utilities, \ - FIRST_COPYRIGHT_YEAR := 2000, \ -)) - -TARGETS += $(jgss) - -################################################################################ - -$(eval $(call SetupJavadocGeneration, smartcardio, \ - MODULES := java.smartcardio, \ - PACKAGES := javax.smartcardio, \ - API_ROOT := jre, \ - DEST_DIR := security/smartcardio/spec, \ - TITLE := Java™ Smart Card I/O, \ - FIRST_COPYRIGHT_YEAR := 2005, \ -)) - -TARGETS += $(smartcardio) - -################################################################################ - -$(eval $(call SetupJavadocGeneration, httpserver, \ - MODULES := jdk.httpserver, \ - PACKAGES := \ - com.sun.net.httpserver \ - com.sun.net.httpserver.spi, \ - API_ROOT := jre, \ - DEST_DIR := net/httpserver/spec, \ - TITLE := Java™ HTTP Server, \ - FIRST_COPYRIGHT_YEAR := 2005, \ - DISABLED_DOCLINT := accessibility missing syntax, \ -)) - -TARGETS += $(httpserver) - -################################################################################ - -$(eval $(call SetupJavadocGeneration, httpclient, \ - MODULES := jdk.incubator.httpclient, \ - PACKAGES := \ - jdk.incubator.http, \ - API_ROOT := jre, \ - DEST_DIR := incubator/httpclient/spec, \ - TITLE := Java™ HTTP Client API (incubator module), \ - FIRST_COPYRIGHT_YEAR := 2015, \ - DISABLED_DOCLINT := accessibility missing syntax, \ -)) - -TARGETS += $(httpclient) - -################################################################################ - -$(eval $(call SetupJavadocGeneration, jsobject, \ - MODULES := jdk.jsobject, \ - PACKAGES := netscape.javascript, \ - API_ROOT := jre, \ - DEST_DIR := plugin/jsobject, \ - FIRST_COPYRIGHT_YEAR := 1993, \ - TITLE := Java™ JSObject Doc, \ -)) - -TARGETS += $(jsobject) - -################################################################################ - -$(eval $(call SetupJavadocGeneration, mgmt, \ - MODULES := jdk.management, \ - PACKAGES := com.sun.management, \ - API_ROOT := jre, \ - DEST_DIR := management/extension, \ - OVERVIEW := $(JDK_TOPDIR)/src/java.management/share/classes/mgmt-overview.html, \ - TITLE := Monitoring and Management Interface for the Java™ Platform, \ - FIRST_COPYRIGHT_YEAR := 2003, \ - DISABLED_DOCLINT := accessibility missing reference, \ -)) - -TARGETS += $(mgmt) - -################################################################################ - -$(eval $(call SetupJavadocGeneration, attach, \ - MODULES := jdk.attach, \ - PACKAGES := \ - com.sun.tools.attach \ - com.sun.tools.attach.spi, \ - API_ROOT := jdk, \ - DEST_DIR := attach/spec, \ - TITLE := Attach API, \ - FIRST_COPYRIGHT_YEAR := 2005, \ - DISABLED_DOCLINT := reference, \ -)) - -TARGETS += $(attach) - -################################################################################ - -$(eval $(call SetupJavadocGeneration, jconsole, \ - MODULES := jdk.jconsole, \ - PACKAGES := com.sun.tools.jconsole, \ - API_ROOT := jdk, \ - DEST_DIR := jconsole/spec, \ - TITLE := JConsole API, \ - FIRST_COPYRIGHT_YEAR := 2006, \ -)) - -TARGETS += $(jconsole) - -################################################################################ - -$(eval $(call SetupJavadocGeneration, jshellapi, \ - MODULES := jdk.jshell, \ - PACKAGES := \ - jdk.jshell \ - jdk.jshell.spi \ - jdk.jshell.execution \ - jdk.jshell.tool, \ - API_ROOT := jdk, \ - DEST_DIR := jshell, \ - TITLE := JShell API, \ - FIRST_COPYRIGHT_YEAR := 2015, \ - SPLIT_INDEX := TRUE, \ -)) - -TARGETS += $(jshellapi) - -################################################################################ - -$(eval $(call SetupJavadocGeneration, treeapi, \ - MODULES := jdk.compiler, \ - PACKAGES := \ - com.sun.source.doctree \ - com.sun.source.tree \ - com.sun.source.util, \ - API_ROOT := jdk, \ - DEST_DIR := javac/tree, \ - TITLE := Compiler Tree API, \ - FIRST_COPYRIGHT_YEAR := 2005, \ - SPLIT_INDEX := TRUE, \ -)) - -TARGETS += $(treeapi) - -################################################################################ - -$(eval $(call SetupJavadocGeneration, nashornapi, \ - MODULES := jdk.scripting.nashorn, \ - PACKAGES := \ - jdk.nashorn.api.scripting \ - jdk.nashorn.api.tree, \ - API_ROOT := jdk, \ - DEST_DIR := nashorn, \ - TITLE := Nashorn API, \ - FIRST_COPYRIGHT_YEAR := 2014, \ - SPLIT_INDEX := TRUE, \ -)) - -TARGETS += $(nashornapi) - -################################################################################ - -$(eval $(call SetupJavadocGeneration, dynalinkapi, \ - MODULES := jdk.dynalink, \ - PACKAGES := \ - jdk.dynalink \ - jdk.dynalink.beans \ - jdk.dynalink.linker \ - jdk.dynalink.linker.support \ - jdk.dynalink.support, \ - API_ROOT := jdk, \ - DEST_DIR := dynalink, \ - TITLE := Dynalink API, \ - FIRST_COPYRIGHT_YEAR := 2015, \ -)) - -TARGETS += $(dynalinkapi) - -################################################################################ - -$(eval $(call SetupJavadocGeneration, sctp, \ - MODULES := jdk.sctp, \ - PACKAGES := com.sun.nio.sctp, \ - API_ROOT := jre, \ - DEST_DIR := nio/sctp/spec, \ - TITLE := SCTP API, \ - FIRST_COPYRIGHT_YEAR := 2009, \ -)) - -TARGETS += $(sctp) - -################################################################################ - -$(eval $(call SetupJavadocGeneration, jaccess, \ - MODULES := jdk.accessibility, \ - PACKAGES := com.sun.java.accessibility.util, \ - API_ROOT := jre, \ - DEST_DIR := accessibility/jaccess/spec, \ - TITLE := JACCESS API, \ - FIRST_COPYRIGHT_YEAR := 2002, \ -)) - -TARGETS += $(jaccess) - -################################################################################ - -$(eval $(call SetupJavadocGeneration, jdknet, \ - MODULES := jdk.net, \ - PACKAGES := jdk.net, \ - API_ROOT := jre, \ - DEST_DIR := net/socketoptions/spec, \ - TITLE := jdk.net API, \ - FIRST_COPYRIGHT_YEAR := 2014, \ - DISABLED_DOCLINT := missing, \ -)) - -TARGETS += $(jdknet) - -################################################################################ -# Copy JDWP html file +# Copy targets JDWP_HTML := $(SUPPORT_OUTPUTDIR)/gensrc/jdk.jdi/jdwp-protocol.html @@ -705,9 +263,6 @@ $(eval $(call SetupCopyFiles, COPY_JDWP_HTML, \ COPY_TARGETS += $(COPY_JDWP_HTML) -################################################################################ -# Copy JVMTI html file - # Pick jvmti.html from any jvm variant, they are all the same. JVMTI_HTML := $(firstword \ $(wildcard $(HOTSPOT_OUTPUTDIR)/variant-*/gensrc/jvmtifiles/jvmti.html)) @@ -722,27 +277,16 @@ COPY_TARGETS += $(COPY_JVMTI_HTML) ################################################################################ # Optional target which bundles all generated javadocs into a zip archive. -JAVADOC_ARCHIVE_NAME := jdk-$(VERSION_STRING)-docs.zip -JAVADOC_ARCHIVE_ASSEMBLY_DIR := $(SUPPORT_OUTPUTDIR)/docs/zip-docs -JAVADOC_ARCHIVE_DIR := $(OUTPUT_ROOT)/bundles -JAVADOC_ARCHIVE := $(JAVADOC_ARCHIVE_DIR)/$(JAVADOC_ARCHIVE_NAME) +JAVADOC_ZIP_NAME := jdk-$(VERSION_STRING)-docs.zip +JAVADOC_ZIP_FILE := $(OUTPUT_ROOT)/bundles/$(JAVADOC_ZIP_NAME) -$(JAVADOC_ARCHIVE): $(TARGETS) $(COPY_TARGETS) - $(call LogInfo, Compressing javadoc to single $(JAVADOC_ARCHIVE_NAME)) - $(MKDIR) -p $(JAVADOC_ARCHIVE_DIR) - $(RM) -r $(JAVADOC_ARCHIVE_ASSEMBLY_DIR) - $(MKDIR) -p $(JAVADOC_ARCHIVE_ASSEMBLY_DIR) - all_roots=`$(FIND) $(JAVADOC_OUTPUTDIR) | $(GREP) index.html | grep -v old/doclet`; \ - pushd $(JAVADOC_ARCHIVE_ASSEMBLY_DIR); \ - for index_file in $${all_roots} ; do \ - target_dir=`dirname $${index_file}`; \ - name=`$(ECHO) $${target_dir} | $(SED) "s;/spec;;" | $(SED) "s;.*/;;"`; \ - $(LN) -s $${target_dir} $${name}; \ - done; \ - $(ZIPEXE) -q -r $(JAVADOC_ARCHIVE) * ; \ - popd ; +$(eval $(call SetupZipArchive, BUILD_JAVADOC_ZIP, \ + SRC := $(JAVADOC_OUTPUTDIR), \ + ZIP := $(JAVADOC_ZIP_FILE), \ + EXTRA_DEPS := $(JAVADOC_TARGETS) $(COPY_TARGETS), \ +)) -ZIP_TARGETS += $(JAVADOC_ARCHIVE) +ZIP_TARGETS += $(BUILD_JAVADOC_ZIP) ################################################################################ # generate .dot files for module graphs @@ -765,14 +309,16 @@ $(eval $(call IncludeCustomExtension, , Javadoc.gmk)) ################################################################################ -docs-module-graphs: $(MODULE_GRAPH_TARGETS) +docs-module-graphs: $(MODULE_GRAPH_TARGETS) -docs-javadoc: $(TARGETS) +docs-javadoc: $(JAVADOC_TARGETS) + +docs-reference: $(REFERENCE_TARGETS) docs-copy: $(COPY_TARGETS) docs-zip: $(ZIP_TARGETS) -all: docs-module-graphs docs-javadoc docs-copy docs-zip +all: docs-module-graphs docs-javadoc docs-reference docs-copy docs-zip -.PHONY: default all docs-module-graphs docs-javadoc docs-copy docs-zip +.PHONY: default all docs-module-graphs docs-javadoc docs-reference docs-copy docs-zip diff --git a/make/Main.gmk b/make/Main.gmk index 19efdf5dc04..5b0514283fe 100644 --- a/make/Main.gmk +++ b/make/Main.gmk @@ -366,6 +366,9 @@ docs-module-graphs: docs-javadoc: +($(CD) $(SRC_ROOT)/make && $(MAKE) $(MAKE_ARGS) -f Javadoc.gmk docs-javadoc) +docs-reference: + +($(CD) $(SRC_ROOT)/make && $(MAKE) $(MAKE_ARGS) -f Javadoc.gmk docs-reference) + docs-copy: +($(CD) $(SRC_ROOT)/make && $(MAKE) $(MAKE_ARGS) -f Javadoc.gmk docs-copy) @@ -375,7 +378,8 @@ docs-zip: update-build-docs: +($(CD) $(SRC_ROOT)/make && $(MAKE) $(MAKE_ARGS) -f UpdateBuildDocs.gmk) -ALL_TARGETS += docs-module-graphs docs-javadoc docs-copy docs-zip update-build-docs +ALL_TARGETS += docs-module-graphs docs-javadoc docs-reference docs-copy \ + docs-zip update-build-docs ################################################################################ # Cross compilation support @@ -772,10 +776,12 @@ else bootcycle-images: jdk-image - docs-module-graphs: exploded-image buildtools-modules + docs-module-graphs: exploded-image buildtools-modules docs-javadoc: $(GENSRC_TARGETS) rmic + docs-reference: $(GENSRC_TARGETS) rmic + # The gensrc step for jdk.jdi creates an html file that is used by docs-copy. docs-copy: hotspot-$(JVM_VARIANT_MAIN)-gensrc jdk.jdi-gensrc diff --git a/make/common/MakeBase.gmk b/make/common/MakeBase.gmk index 97368dc2599..0a9c6b6da46 100644 --- a/make/common/MakeBase.gmk +++ b/make/common/MakeBase.gmk @@ -672,9 +672,9 @@ ifneq ($(DISABLE_CACHE_FIND), true) # Param 1 - Dirs to find in # Param 2 - (optional) specialization. Normally "-a \( ... \)" expression. define CacheFind - $(if $(filter-out $(addsuffix /%,- $(FIND_CACHE_DIRS)) $(FIND_CACHE_DIRS),$1), \ - $(shell $(FIND) $1 \( -type f -o -type l \) $2), \ - $(filter $(addsuffix /%,$(patsubst %/,%,$1)) $1,$(FIND_CACHE))) + $(if $(filter-out $(addsuffix /%,- $(FIND_CACHE_DIRS)) $(FIND_CACHE_DIRS),$1), \ + $(if $(wildcard $1), $(shell $(FIND) $1 \( -type f -o -type l \) $2)), \ + $(filter $(addsuffix /%,$(patsubst %/,%,$1)) $1,$(FIND_CACHE))) endef else diff --git a/make/common/Modules.gmk b/make/common/Modules.gmk index 8e8b7712255..410d6fe510b 100644 --- a/make/common/Modules.gmk +++ b/make/common/Modules.gmk @@ -40,6 +40,7 @@ PLATFORM_MODULES := JRE_TOOL_MODULES := UPGRADEABLE_MODULES := AGGREGATOR_MODULES := +DOCS_MODULES := # Hook to include the corresponding custom file, if present. $(eval $(call IncludeCustomExtension, , common/Modules.gmk)) @@ -58,12 +59,12 @@ BOOT_MODULES += \ java.security.sasl \ java.xml \ jdk.httpserver \ + jdk.internal.vm.ci \ jdk.management \ jdk.management.agent \ jdk.net \ jdk.sctp \ jdk.unsupported \ - jdk.internal.vm.ci \ # # to be deprivileged @@ -96,7 +97,6 @@ PLATFORM_MODULES += \ PLATFORM_MODULES += \ java.compiler \ - jdk.incubator.httpclient \ java.scripting \ java.security.jgss \ java.smartcardio \ @@ -105,32 +105,71 @@ PLATFORM_MODULES += \ java.xml.crypto \ jdk.accessibility \ jdk.charsets \ - jdk.crypto.ec \ jdk.crypto.cryptoki \ + jdk.crypto.ec \ jdk.dynalink \ + jdk.incubator.httpclient \ + jdk.internal.vm.compiler \ jdk.jsobject \ jdk.localedata \ jdk.naming.dns \ jdk.scripting.nashorn \ jdk.security.auth \ jdk.security.jgss \ - jdk.internal.vm.compiler \ jdk.xml.dom \ jdk.zipfs \ # +ifeq ($(OPENJDK_TARGET_OS), windows) + PLATFORM_MODULES += jdk.crypto.mscapi +endif + +ifeq ($(OPENJDK_TARGET_OS), solaris) + PLATFORM_MODULES += jdk.crypto.ucrypto +endif + JRE_TOOL_MODULES += \ jdk.jdwp.agent \ jdk.pack \ jdk.scripting.nashorn.shell \ # -ifeq ($(OPENJDK_TARGET_OS), windows) - PLATFORM_MODULES += jdk.crypto.mscapi -endif -ifeq ($(OPENJDK_TARGET_OS), solaris) - PLATFORM_MODULES += jdk.crypto.ucrypto -endif +################################################################################ + +# DOCS_MODULES defines the root modules for javadoc generation. +# All of their `require transitive` modules directly and indirectly will be included. +DOCS_MODULES += \ + java.se.ee \ + java.smartcardio \ + jdk.accessibility \ + jdk.attach \ + jdk.charsets \ + jdk.compiler \ + jdk.crypto.cryptoki \ + jdk.crypto.ec \ + jdk.dynalink \ + jdk.editpad \ + jdk.httpserver \ + jdk.incubator.httpclient \ + jdk.jartool \ + jdk.javadoc \ + jdk.jconsole \ + jdk.jdeps \ + jdk.jdi \ + jdk.jlink \ + jdk.jshell \ + jdk.localedata \ + jdk.management \ + jdk.naming.dns \ + jdk.naming.rmi \ + jdk.net \ + jdk.scripting.nashorn \ + jdk.sctp \ + jdk.security.auth \ + jdk.security.jgss \ + jdk.xml.dom \ + jdk.zipfs \ + # # These modules are included in the interim image which is used to run profiling # before building the real images. @@ -329,6 +368,7 @@ define ReadSingleImportMetaData else ifeq ($$(classloader), ext) PLATFORM_MODULES += $1 endif + DOCS_MODULES += $1 else # Default to include in all JRE_MODULES += $1