# Copyright (c) 1997, 2016, 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

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

# List of all possible directories for javadoc to look for sources

# Allow custom to overwrite.

JAVADOC_SOURCE_DIRS = \

      $(SUPPORT_OUTPUTDIR)/gensrc/* \

      $(if $(IMPORT_MODULES_SRC), $(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

# The core api index file is the target for the core api javadocs rule

# and needs to be defined early so that all other javadoc rules may

# depend on it.

CORE_INDEX_FILE := $(JAVADOC_OUTPUTDIR)/api/index.html

# Symbols

TRADEMARK := ™

COPYRIGHT_SYMBOL := &$(HASH)x00a9;

COPYRIGHT_TEXT := Copyright

ALL_RIGHTS_RESERVED := All rights reserved.

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

JAVA_TRADEMARK_LINE := Java is a trademark or registered trademark of \

    $(FULL_COMPANY_NAME) in the US and other countries.

COMMON_BOTTOM_ADDRESS := $(COMPANY_ADDRESS)

COMMON_BOTTOM_TEXT := $(BUG_SUBMIT_LINE)<br>$(JAVA_TRADEMARK_LINE)

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_HEADER :=

  DRAFT_BOTTOM :=

  DRAFT_WINTITLE :=

  CORE_TOP_EARLYACCESS :=

else

  # We need a draft format when not building the GA version.

  DRAFT_HEADER := <br><strong>DRAFT&nbsp;$(VERSION_STRING)</strong>

  DRAFT_BOTTOM := <br><strong>DRAFT&nbsp;$(VERSION_STRING)</strong>

  DRAFT_WINTITLE := $(VERSION_BUILD)

  CORE_TOP_EARLYACCESS := \

<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

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

# Support functions for SetupJavadocGeneration

# Print an option line to the target file

# Arguments:

# arg 1: the option name

# arg 2-3: optional arguments to the option

define AddOption

	$(PRINTF) "%s$(if $(strip $2), '%s',)$(if $(strip $3), '%s',)\n" \

	    "$(strip $1)"$(if $(strip $2), '$(strip $2)',)$(if $(strip $3), \

	    '$(strip $3)',) >> $@

endef

# This function goes to great pains to exactly mimic the old behavior

# in all details, including whitespace.

# Note that COPYRIGHT_YEAR is the current year (from spec.gmk)

# Arguments:

# arg 1: first copyright year

# arg 2: copyright url (optional)

# arg 3: company address (optional)

# arg 4: free-form text snippet (optional)

define GenerateBottom

  <font size="-1">$(if $(strip $4), $(strip $4))<br> $(if \

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

      $(COPYRIGHT_SYMBOL) $(strip $1), $(COPYRIGHT_YEAR), \

      $(FULL_COMPANY_NAME). $(strip $3) \

      $(ALL_RIGHTS_RESERVED)$(if $(strip $4), )</font>

endef

# Speed up finding by filling cache

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

# Prevent # from expanding

EscapeHash = $(subst $(HASH),{hash},$(strip $1))

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

# 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

#   PACKAGE_FILTER - Filter for packages

#   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

#   DOCLINT - Doclint level. Defaults to "all".

#   DOCLINT_PACKAGES - Optional -Xdoclint/package value

#   ENCODING - Change character encoding (defaults to 'ascii')

#   SPLIT_INDEX - Enable -splitIndex

#   BREAKITERATOR - Enable -breakiterator

#   NODEPRECATEDLIST - Enable nodeprecatedlist

#   NOINDEX - Enable -noindex and -nonavbar

#   BOTTOM_COPYRIGHT_URL - Copyright URL to use in -bottom

#   BOTTOM_ADDRESS - Company address 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)

    ifeq ($$($1_RELATIVE_CORE_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

      # NOTE: Need to be able to override for broken old code in JShell

      $1_RELATIVE_CORE_DIR := $$(strip $$(subst $$(call DirToDotDot, \

          $$(JAVADOC_OUTPUTDIR))/,, $$(call DirToDotDot, \

          $$(JAVADOC_OUTPUTDIR)/$$($1_OUTPUT_DIRNAME))))

    endif

    $1_DEPS += $(CORE_INDEX_FILE)

  endif

  ifneq ($$($1_OVERVIEW), )

    $1_DEPS +=  $$($1_OVERVIEW)

  endif

  ifeq ($$($1_ENCODING), )

    $1_ENCODING := ascii

  endif

  ifeq ($$($1_DOCLINT), )

    $1_DOCLINT := all

  endif

  ifeq ($$($1_DOC_TITLE), )

    $1_DOC_TITLE := $$($1_TITLE)

  endif

  ifeq ($$($1_WINDOW_TITLE), )

    $1_WINDOW_TITLE := $$(strip $$(subst $$(TRADEMARK),, $$($1_TITLE)))

  endif

  ifeq ($$($1_HEADER_TITLE), )

    $1_HEADER_TITLE := $$(strip $$(subst $$(TRADEMARK),, $$($1_TITLE)))

  endif

  $1_HEADER := <strong>$$($1_HEADER_TITLE)</strong>

  $1_BOTTOM := $$(call GenerateBottom, $$($1_FIRST_COPYRIGHT_YEAR), \

      $$($1_BOTTOM_COPYRIGHT_URL), $$($1_BOTTOM_ADDRESS), $$($1_BOTTOM_TEXT))

  # The index.html, options, and packages files

  $1_INDEX_FILE := $$(JAVADOC_OUTPUTDIR)/$$($1_OUTPUT_DIRNAME)/index.html

  $1_OPTIONS_FILE := $$(SUPPORT_OUTPUTDIR)/docs/$1.options

  $1_PACKAGES_FILE := $$(SUPPORT_OUTPUTDIR)/docs/$1.packages

  $1_PACKAGES_VARDEPS := $$($1_PACKAGES) $$($1_PACKAGES_SINGLE_CLASS)

  $1_PACKAGES_VARDEPS_FILE := $$(call DependOnVariable, $1_PACKAGES_VARDEPS, \

       $$($1_PACKAGES_FILE).vardeps)

  # Rule for creating a file with the package names in it

  $$($1_PACKAGES_FILE): $$($1_PACKAGES_VARDEPS_FILE)

	$$(call LogInfo, Creating Javadoc package file for $1)

	$$(call MakeDir, $$(@D))

        ifeq ($$($1_PACKAGES_SINGLE_CLASS), )

	  $$(ECHO) $$($1_PACKAGES) | $$(TR) ' ' '\n' > $$@

        else

          # NOTE: This is for backwards compatibility for taglet

	  $$(ECHO) $$($1_PACKAGES_SINGLE_CLASS) > $$@

        endif

  # NOTE: Not including $$($1_EXTRA_TOP) due to $$(HASH)

  $1_OPTIONS_VARDEPS := $$(call EscapeHash, \

      $$($DOCROOTPARENT_FLAG) $$(JAVADOC_BASE_URL) $$($1_NO_COMMON_TAGS) \

      $$($1_DOCLINT) $$($1_DOCLINT_PACKAGES) $$(JAVADOC_SOURCE_DIRS) \

      $$($1_MODULES) $$($1_ENCODING) $$($1_NODEPRECATEDLIST) \

      $$($1_BREAKITERATOR) $$($1_SPLIT_INDEX) $$($1_OVERVIEW) \

      $$($1_DOC_TITLE) $$($1_WINDOW_TITLE) $$(DRAFT_WINTITLE) \

      $$($1_HEADER) $$(DRAFT_HEADER) $$($1_NOINDEX) $$($1_EXTRA_TOP_2) \

      $$($1_BOTTOM) $$(DRAFT_BOTTOM)) $$($1_PACKAGE_FILTER) $$($1_RELATIVE_CORE_DIR) \

      $$(JAVADOC_OUTPUTDIR) \

  )

  $1_OPTIONS_VARDEPS_FILE := $$(call DependOnVariable, $1_OPTIONS_VARDEPS, \

       $$($1_OPTIONS_FILE).vardeps)

  # Rule for creating a file with javadoc options in it

  $$($1_OPTIONS_FILE): $$($1_OPTIONS_VARDEPS_FILE)

	$$(call LogInfo, Creating Javadoc options file for $1)

	$$(call MakeDir, $$(@D))

	$$(RM) $$@

	$$(call AddOption, -XDignore.symbol.file=true)

        ifneq ($$(LOG_LEVEL), trace)

	  $$(call AddOption, -quiet)

        endif

	$$(call AddOption, -use)

	$$(call AddOption, -keywords)

        ifneq ($$($DOCROOTPARENT_FLAG), )

          # NOTE: Argument to -Xdocrootparent is not quoted to keep backwards compatibility.

	  $$(call AddOption, -Xdocrootparent $(JAVADOC_BASE_URL))

        endif

        ifneq ($$($1_NO_COMMON_TAGS), TRUE)

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

	  $$(call AddOption, -tag, beaninfo:X)

	  $$(call AddOption, -tag, revised:X)

	  $$(call AddOption, -tag, since.unbundled:X)

	  $$(call AddOption, -tag, spec:X)

	  $$(call AddOption, -tag, specdefault:X)

	  $$(call AddOption, -tag, Note:X)

	  $$(call AddOption, -tag, ToDo:X)

	  $$(call AddOption, -tag, apiNote:a:API Note:)

	  $$(call AddOption, -tag, implSpec:a:Implementation Requirements:)

	  $$(call AddOption, -tag, implNote:a:Implementation Note:)

	  $$(call AddOption, -tag, param)

	  $$(call AddOption, -tag, return)

	  $$(call AddOption, -tag, throws)

	  $$(call AddOption, -tag, since)

	  $$(call AddOption, -tag, version)

	  $$(call AddOption, -tag, serialData)

	  $$(call AddOption, -tag, factory)

	  $$(call AddOption, -tag, see)

	  $$(call AddOption, -tag, \

              jvms:a:See <cite> The Java&trade; Virtual Machine Specification</cite>:)

	  $$(call AddOption, -tag, \

              jls:a:See <cite> The Java&trade; Language Specification</cite>:)

        endif

	$$(call AddOption, -Xdoclint:$$($1_DOCLINT))

        ifneq ($$($1_DOCLINT_PACKAGES), )

	  $$(call AddOption, -Xdoclint/package:$$(call CommaList, $$($1_DOCLINT_PACKAGES)))

        endif

	$$(call AddOption, --system, none)

	$$(call AddOption, --module-source-path, $$(subst ",, $$(call PathList, $$(JAVADOC_SOURCE_DIRS))))

	$$(call AddOption, --add-modules, $$(call CommaList, $$($1_MODULES)))

	$$(call AddOption, -encoding, $$($1_ENCODING))

        ifneq ($$($1_NODEPRECATEDLIST), )

	  $$(call AddOption, -nodeprecatedlist)

        endif

        ifneq ($$($1_BREAKITERATOR), )

	  $$(call AddOption, -breakiterator)

        endif

        ifneq ($$($1_SPLIT_INDEX), )

	  $$(call AddOption, -splitIndex)

        endif

        ifneq ($$($1_OVERVIEW), )

	  $$(call AddOption, -overview, $$($1_OVERVIEW))

        endif

	$$(call AddOption, -doctitle, $$($1_DOC_TITLE))

	$$(call AddOption, -windowtitle, $$($1_WINDOW_TITLE) $$(DRAFT_WINTITLE))

	$$(call AddOption, -header, $$($1_HEADER)$$(DRAFT_HEADER))

        ifneq ($$($1_NOINDEX), )

	  $$(call AddOption, -nonavbar)

	  $$(call AddOption, -noindex)

        endif

        ifneq ($$($1_EXTRA_TOP_2), )

	  $$(call AddOption, -top,$$($1_EXTRA_TOP_2))

        endif

	$$(call AddOption, -bottom, $$($1_BOTTOM)$$(DRAFT_BOTTOM))

        ifneq ($$($1_PACKAGE_FILTER), )

	  $$(call AddOption, -group, Packages, $$($1_PACKAGE_FILTER))

        endif

        ifneq ($$($1_RELATIVE_CORE_DIR), )

	  $$(call AddOption, -linkoffline, $$($1_RELATIVE_CORE_DIR)/api, $$(JAVADOC_OUTPUTDIR)/api/)

        endif

        ifneq ($$($1_EXTRA_TOP), )

	  $$(call AddOption, -top, $$($1_EXTRA_TOP))

        endif

  $1_PACKAGE_DEPS := $$(call CacheFind, $$(wildcard $$(foreach p, \

      $$(subst .,/,$$(strip $$($1_PACKAGES))), \

      $$(addsuffix /$$p, $$(wildcard $$(JAVADOC_SOURCE_DIRS))))))

  # Rule for actually running javadoc

  $$($1_INDEX_FILE): $$($1_OPTIONS_FILE) $$($1_PACKAGES_FILE) \

    $$($1_PACKAGE_DEPS) $$($1_DEPS)

	$$(call LogWarn, Generating Javadoc for $$($1_OUTPUT_DIRNAME))

	$$(call MakeDir, $$(@D))

        ifneq ($$(findstring $$(LOG_LEVEL), debug trace),)

	  $$(ECHO) "Contents of $$($1_OPTIONS_FILE):" `$$(CAT) $$($1_OPTIONS_FILE)`

	  $$(ECHO) "Contents of $$($1_PACKAGES_FILE):" `$$(CAT) $$($1_PACKAGES_FILE)`

        endif

	$$(call ExecuteWithLog, $$(SUPPORT_OUTPUTDIR)/docs/$1.javadoc, \

	    $$($1_JAVA) -Djava.awt.headless=true $(NEW_JAVADOC) -d $$(@D) \

	    @$$($1_OPTIONS_FILE) @$$($1_PACKAGES_FILE))

	$$(TOUCH) $$($1_INDEX_FILE)

  # The output returned will be the index.html file

  $1 := $$($1_INDEX_FILE)

endef

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

CORE_PACKAGES := \

    java.applet \

    java.awt \

    java.awt.color \

    java.awt.datatransfer \

    java.awt.desktop \

    java.awt.dnd \

    java.awt.event \

    java.awt.font \

    java.awt.geom \

    java.awt.im \

    java.awt.im.spi \

    java.awt.image \

    java.awt.image.renderable \

    java.awt.print \

    java.beans \

    java.beans.beancontext \

    java.io \

    java.lang \

    java.lang.annotation \

    java.lang.instrument \

    java.lang.invoke \

    java.lang.management \

    java.lang.module \

    java.lang.ref \

    java.lang.reflect \

    java.math \

    java.net \

    java.net.http \

    java.net.spi \

    java.nio \

    java.nio.channels \

    java.nio.channels.spi \

    java.nio.charset \

    java.nio.charset.spi \

    java.nio.file \

    java.nio.file.attribute \

    java.nio.file.spi \

    java.rmi \

    java.rmi.activation \

    java.rmi.dgc \

    java.rmi.registry \

    java.rmi.server \

    java.security \

    java.security.acl \

    java.security.cert \

    java.security.interfaces \

    java.security.spec \

    java.sql \

    java.text \

    java.text.spi \

    java.time \

    java.time.chrono \

    java.time.format \

    java.time.temporal \

    java.time.zone \

    java.util \

    java.util.concurrent \

    java.util.concurrent.atomic \

    java.util.concurrent.locks \

    java.util.function \

    java.util.jar \

    java.util.logging \

    java.util.prefs \

    java.util.regex \

    java.util.spi \

    java.util.stream \

    java.util.zip \

    javax.accessibility \

    javax.activation \

    javax.activity \

    javax.annotation \

    javax.annotation.processing \

    javax.crypto \

    javax.crypto.interfaces \

    javax.crypto.spec \

    javax.imageio \

    javax.imageio.event \

    javax.imageio.metadata \

    javax.imageio.plugins.jpeg \

    javax.imageio.plugins.bmp \

    javax.imageio.plugins.tiff \

    javax.imageio.spi \

    javax.imageio.stream \

    javax.jws \

    javax.jws.soap \

    javax.lang.model \

    javax.lang.model.element \

    javax.lang.model.type \

    javax.lang.model.util \

    javax.management \

    javax.management.loading \

    javax.management.monitor \

    javax.management.relation \

    javax.management.openmbean \

    javax.management.timer \

    javax.management.modelmbean \

    javax.management.remote \

    javax.management.remote.rmi \

    javax.naming \

    javax.naming.directory \

    javax.naming.event \

    javax.naming.ldap \

    javax.naming.spi \

    javax.net \

    javax.net.ssl \

    javax.print \

    javax.print.attribute \

    javax.print.attribute.standard \

    javax.print.event \

    javax.rmi \

    javax.rmi.CORBA \

    javax.rmi.ssl \

    javax.script \

    javax.security.auth \

    javax.security.auth.callback \

    javax.security.auth.kerberos \

    javax.security.auth.login \

    javax.security.auth.spi \

    javax.security.auth.x500 \

    javax.security.cert \

    javax.security.sasl \

    javax.sound.sampled \

    javax.sound.sampled.spi \

    javax.sound.midi \

    javax.sound.midi.spi \