# Copyright (c) 1997, 2017, Oracle and/or its affiliates. All rights reserved.

# DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

#

# This code is free software; you can redistribute it and/or modify it

# under the terms of the GNU General Public License version 2 only, as

# published by the Free Software Foundation.  Oracle designates this

# particular file as subject to the "Classpath" exception as provided

# by Oracle in the LICENSE file that accompanied this code.

#

# This code is distributed in the hope that it will be useful, but WITHOUT

# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or

# FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License

# version 2 for more details (a copy is included in the LICENSE file that

# accompanied this code).

#

# You should have received a copy of the GNU General Public License version

# 2 along with this work; if not, write to the Free Software Foundation,

# Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

#

# Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA

# or visit www.oracle.com if you need additional information or have any

# questions.

#

default: all

include $(SPEC)

include MakeBase.gmk

include $(JDK_TOPDIR)/make/Tools.gmk

################################################################################

# 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 \

      #

# 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<br>Redwood Shores, CA 94065 USA

BUG_SUBMIT_LINE := <a href="$(BUG_SUBMIT_URL)">Submit a bug or feature</a>

COMMON_BOTTOM_TEXT := $(BUG_SUBMIT_LINE)<br> 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) \

    <br>For further API reference and developer documentation, see \

    <a href="$(JAVADOC_BASE_URL)/index.html" target="_blank">Java SE \

    Documentation</a>. 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 := <br><strong>DRAFT&nbsp;$(VERSION_STRING)</strong>

  ifeq ($(VERSION_BUILD), 0)

    DRAFT_WINDOW_TITLE_MARKER := $(SPACE)[ad-hoc build]

  else

    DRAFT_WINDOW_TITLE_MARKER := $(SPACE)[build $(VERSION_BUILD)]

  endif

  EARLYACCESS_TOP := \

      <div style="background-color: $(HASH)EEEEEE"><div style="padding: 6px; \

      margin-top: 2px; margin-bottom: 6px; margin-left: 6px; margin-right: \

      6px; text-align: justify; font-size: 80%; font-family: Helvetica, Arial, \

      sans-serif; font-weight: normal;">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.</div></div>

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

  <span style="font-size:smaller">$(if $(strip $3), $(strip $3))<br> $(if \

      $(strip $2),<a href="$(strip $2)">Copyright</a>,Copyright) \

      © $(strip $1), $(COPYRIGHT_YEAR), $(FULL_COMPANY_NAME). \

      $(COMPANY_ADDRESS). All rights reserved.</span>

endef

# Speed up finding by filling cache

$(eval $(call FillCacheFind, $(wildcard $(JAVADOC_SOURCE_DIRS))))

# 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 := \

    -tag beaninfo:X \

    -tag revised:X \

    -tag since.unbundled:X \

    -tag spec:X \

    -tag specdefault:X \

    -tag Note:X \

    -tag ToDo:X \

    -tag 'apiNote:a:API Note:' \

    -tag 'implSpec:a:Implementation Requirements:' \

    -tag 'implNote:a:Implementation Note:' \

    -tag param \

    -tag return \

    -tag throws \

    -tag since \

    -tag version \

    -tag serialData \

    -tag factory \

    -tag see \

    -tag 'jvms:a:See <cite>The Java&trade; Virtual Machine Specification</cite>:' \

    -tag 'jls:a:See <cite>The Java&trade; Language Specification</cite>:' \

    -taglet build.tools.taglet.Incubating \

    -tagletpath $(BUILDTOOLS_OUTPUTDIR)/jdk_tools_classes \

    #

DEFAULT_JAVADOC_OPTIONS := -XDignore.symbol.file=true -use -keywords -notimestamp \

    -serialwarn -encoding ISO-8859-1 -breakiterator --system none

################################################################################

# 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 '<strong>$$($1_HEADER_TITLE)</strong>$$(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 $(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&trade;&nbsp;Platform<br>Standard&nbsp;Ed.&nbsp;$(VERSION_SPECIFICATION), \

    DOC_TITLE := Java™ Platform$(COMMA) Standard Edition \

      $(VERSION_SPECIFICATION)<br>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 \

        jdk.javadoc.doclet.taglet \

        jdk.javadoc.doclets, \

    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, \

))