--- old/make/Javadoc.gmk 2017-03-30 14:59:43.302579844 +0200 +++ new/make/Javadoc.gmk 2017-03-30 14:59:43.190581620 +0200 @@ -26,10 +26,16 @@ 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)) + ################################################################################ +# Javadoc settings # List of all possible directories for javadoc to look for sources # Allow custom to overwrite. @@ -49,119 +55,20 @@ $(JDK_TOPDIR)/src/*/share/doc/stub \ # +# All modules to have docs generated by docs-javadoc target +JAVADOC_MODULES := $(sort $(DOCS_MODULES)) + # Should we use -Xdocrootparent? Allow custom to overwrite. 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 +94,13 @@ -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 +109,139 @@ ENABLE_MODULE_GRAPH=false 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 - 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) - 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 +# Should we add DRAFT stamps to the generated javadoc? +ifeq ($(VERSION_IS_GA), true) + IS_DRAFT := false +else + IS_DRAFT := true +endif - ifneq ($$($DOCROOTPARENT_FLAG), ) - $1_OPTIONS += -Xdocrootparent $(JAVADOC_BASE_URL) - endif +################################################################################ +# Text snippets - $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 +FULL_COMPANY_NAME := Oracle and/or its affiliates +COMPANY_ADDRESS := 500 Oracle Parkway
Redwood Shores, CA 94065 USA - $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) +ifeq ($(IS_DRAFT), true) + DRAFT_MARKER_STR :=
DRAFT $(VERSION_STRING) + ifeq ($(VERSION_BUILD), 0) + DRAFT_MARKER_TITLE := [ad-hoc build] else - $1_PACKAGES_ARG := $$($1_PACKAGES) + DRAFT_MARKER_TITLE := [build $(VERSION_BUILD)] endif +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 - -################################################################################ - -$(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), \ -)) - -TARGETS += $(coredocs) - -################################################################################ - -$(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) - -################################################################################ - -$(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, \ -)) - -TARGETS += $(old-docletapi) - -################################################################################ - -$(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, \ -)) - -TARGETS += $(tagletapi) - -################################################################################ - -$(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) +JAVADOC_WINDOW_TITLE := Java Platform SE $(VERSION_SPECIFICATION) \ + $(DRAFT_MARKER_TITLE) -################################################################################ +JAVADOC_DOC_TITLE := Java™ Platform, Standard Edition \ + $(VERSION_SPECIFICATION)
API Specification -$(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, \ -)) +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) -TARGETS += $(dynalinkapi) +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.
################################################################################ +# Setup call to javadoc based on above settings -$(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) - -################################################################################ +# Create a string like "-Xdoclint:all,-syntax,-html,..." +JAVADOC_OPTIONS += -Xdoclint:all,$(call CommaList, $(addprefix -, \ + $(JAVADOC_DISABLED_DOCLINT))) -$(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, \ -)) +ifneq ($($DOCROOTPARENT_FLAG), ) + JAVADOC_OPTIONS += -Xdocrootparent $(JAVADOC_BASE_URL) +endif -TARGETS += $(jaccess) +JAVADOC_OPTIONS += -doctitle '$(JAVADOC_DOC_TITLE)' +JAVADOC_OPTIONS += -windowtitle '$(JAVADOC_WINDOW_TITLE)' +JAVADOC_OPTIONS += -header '$(JAVADOC_HEADER_TITLE)' +JAVADOC_OPTIONS += -bottom '$(JAVADOC_BOTTOM)' +ifeq ($(IS_DRAFT), true) + JAVADOC_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 -$(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, \ -)) +JAVADOC_VARDEPS := $(JAVADOC_OPTIONS) $(JAVADOC_TAGS) $(JAVADOC_MODULES) +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) \ + -overview $(JAVADOC_OVERVIEW) \ + --module-source-path $(call PathList, $(JAVADOC_SOURCE_DIRS)) \ + --module $(call CommaList, $(JAVADOC_MODULES))) + +JAVADOC_TARGETS += $(JAVADOC_TARGET_DIR)/index.html + +################################################################################ +# Generate reference javadoc for Java SE + +REFERENCE_TARGET_DIR := $(SUPPORT_OUTPUTDIR)/javase-api +REFERENCE_OVERVIEW := $(JDK_TOPDIR)/src/java.base/share/classes/overview-core.html + +# Javadoc creates a lot of files but use index.html as a marker. +$(REFERENCE_TARGET_DIR)/index.html: $(BUILD_TOOLS_JDK) $(JAVADOC_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) \ + -overview $(REFERENCE_OVERVIEW) \ + --module-source-path $(call PathList, $(JAVADOC_SOURCE_DIRS)) \ + --module $(call CommaList, java.base java.se.ee)) -TARGETS += $(jdknet) +REFERENCE_TARGETS += $(REFERENCE_TARGET_DIR)/index.html ################################################################################ -# Copy JDWP html file +# Copy targets JDWP_HTML := $(SUPPORT_OUTPUTDIR)/gensrc/jdk.jdi/jdwp-protocol.html @@ -705,9 +252,6 @@ 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 +266,16 @@ ################################################################################ # 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_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 ; +JAVADOC_ZIP_NAME := jdk-$(VERSION_STRING)-docs.zip +JAVADOC_ZIP_FILE := $(OUTPUT_ROOT)/bundles/$(JAVADOC_ZIP_NAME) -ZIP_TARGETS += $(JAVADOC_ARCHIVE) +$(eval $(call SetupZipArchive, BUILD_JAVADOC_ZIP, \ + SRC := $(JAVADOC_OUTPUTDIR), \ + ZIP := $(JAVADOC_ZIP_FILE), \ + EXTRA_DEPS := $(JAVADOC_TARGETS) $(COPY_TARGETS), \ +)) + +ZIP_TARGETS += $(BUILD_JAVADOC_ZIP) ################################################################################ # generate .dot files for module graphs @@ -765,14 +298,16 @@ ################################################################################ -docs-module-graphs: $(MODULE_GRAPH_TARGETS) +docs-module-graphs: $(MODULE_GRAPH_TARGETS) + +docs-javadoc: $(JAVADOC_TARGETS) -docs-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