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

#

#

# Definitions for $(DOCSDIR), $(MKDIR), $(BINDIR), etc.

#

BUILDDIR=..

PRODUCT=docs

include $(BUILDDIR)/common/Defs.gmk

# Get CopyrightLine macro and other shared variables

include $(BUILDDIR)/common/shared/Defs-javadoc.gmk

# Url to root of documents

DOCSDIR_URL = {@docroot}/$(GET2DOCSDIR)

# Url to copyright html file

COPYRIGHT_URL-7 = $(DOCSDIR_URL)/legal/cpyr.html

COPYRIGHT_URL = $(COPYRIGHT_URL-$(JDK_MINOR_VERSION))

# Url to bug filing site

BUG_SUBMIT_URL = http://bugreport.sun.com/bugreport/

# Common line for how to submit a bug or rfe

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

# Url to devdocs page

#   Was: http://java.sun.com/javase/6/webnotes/devdocs-vs-specs.html

DEV_DOCS_URL-5 = http://java.sun.com/j2se/1.5.0/docs/index.html

DEV_DOCS_URL-6 = http://download.oracle.com/javase/6/docs/index.html

DEV_DOCS_URL-7 = http://download.oracle.com/javase/7/docs/index.html

DEV_DOCS_URL = $(DEV_DOCS_URL-$(JDK_MINOR_VERSION))

DOCS_BASE_URL = http://download.oracle.com/javase/7/docs

# Url to Java Language Spec

#JLS3_URL = http://java.sun.com/docs/books/jls/

# Common Java trademark line

JAVA_TRADEMARK_LINE = Java is a trademark or registered trademark of \

$(FULL_COMPANY_NAME) in the US and other countries.

#

# Definitions for imported components

#

include $(BUILDDIR)/common/internal/ImportComponents.gmk

# We override whatever the max VM memory setting is here.

#    NOTE: javadoc will not complete without these larger settings.

#    WARNING: This could cause thrashing on low memory machines.

ifeq ($(ARCH_DATA_MODEL),64)

  MAX_VM_MEMORY = 1024

else

  MAX_VM_MEMORY = 612

endif

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

#    NOTE: Quotes are required around sourcepath argument only on Windows.

#          Otherwise, you get "No packages or classes specified." due 

#          to $(CLASSPATH_SEPARATOR) being interpreted as an end of 

#          command (newline or shell ; character)

ALL_SOURCE_DIRS = $(SHARE_SRC)/classes \

                  $(IMPORTSRCDIR) \

                  $(GENSRCDIR) \

                  $(SHARE_SRC)/../solaris/classes \

	          $(SHARE_SRC)/../windows/classes \

		  $(SHARE_SRC)/doc/stub

# List of directories that actually exist

ALL_EXISTING_SOURCE_DIRS := $(wildcard $(ALL_SOURCE_DIRS))

# List with classpath separator between them

EMPTY:=

SPACE:= $(EMPTY) $(EMPTY)

RELEASEDOCS_SOURCEPATH = \

    $(subst $(SPACE),$(CLASSPATH_SEPARATOR),$(strip $(ALL_SOURCE_DIRS)))

# Prep for javadoc creation, assumes $@ is an index.html file

define prep-javadoc

@if [ -f "$@" -a "$?" != "" ] ; then \

  $(ECHO) "# Dependencies have changed: $?"; \

fi

$(RM) -r $(@D)

$(MKDIR) -p $(@D)

endef

# A cache of the directories in ALL_SOURCE_DIRS

DIRECTORY_CACHE = $(DOCSTMPDIR)/directory.cache

# Given a list of packages, return a list of files or dirs to be dependent on

#   (Currently only returning a list of directories)

define PackageDependencies # packages

$(shell							\

  if [ "$1" != "" -a -f $(DIRECTORY_CACHE) ] ; then	\

    for p in $1 ; do 					\

      pd=`$(ECHO) $${p} | $(SED) -e 's@[.]@/@g'`;	\

      $(CAT) $(DIRECTORY_CACHE) | $(GREP) "/$${pd}/" ; 	\

    done; 						\

  fi							\

)

endef

# Given a list of packages, add packages that exist to $@, print summary

define PackageFilter # packages

@if [ "$1" != "" ] ; then 				\

  for p in $1 ; do 					\

    pd=`$(ECHO) $${p} | $(SED) -e 's@[.]@/@g'`; 	\

    found="false"; 					\

    for cp in $(ALL_SOURCE_DIRS) ; do 			\

      if [ -d $${cp}/$${pd} ] ; then 			\

        $(ECHO) "$${p}" >> $@; 				\

	found="true";					\

	break; 						\

      fi; 						\

    done; 						\

    if [ "$${found}" = "false" ] ; then 		\

      $(ECHO) "WARNING: Package not found: $${p}"; 	\

    fi; 						\

  done; 						\

fi

endef

# Print out a summary of the javadoc command about to be run

define JavadocSummary # optionsfile packagesfile

@$(ECHO) "# Summary for $@";\

 $(ECHO) "# Options (`$(BASENAME) $1`):"; $(SED) -e 's@^@#   @' $1; \

 $(ECHO) "# Packages (`$(BASENAME) $2`):";$(SED) -e 's@^@#   @' $2

endef

#

# Temporary directory for javadoc creation

#

DOCSTMPDIR = $(TEMPDIR)/doctmp

#

# Different api directories created from root directory

#

COREAPI_DOCSDIR   = $(DOCSDIR)/api

JDK_API_DOCSDIR   = $(DOCSDIR)/jdk/api

JRE_API_DOCSDIR   = $(DOCSDIR)/jre/api

PLATFORM_DOCSDIR  = $(DOCSDIR)/platform

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

JDKJRE2COREAPI    = ../../api

# Common bottom argument

define CommonBottom # year

<font size="-1"><br> $(call CopyrightLine,,$1,)</font>

endef

# Common trademark bottom argument (Not sure why this is used sometimes)

define CommonTrademarkBottom # year

<font size="-1">\

$(BUG_SUBMIT_LINE)<br>$(JAVA_TRADEMARK_LINE)<br>\

$(call CopyrightLine,,$1,$(COMPANY_ADDRESS))\

</font>

endef

# Common echo of option

define OptionOnly # opt

$(PRINTF) "%s\n" "$1"

endef

define OptionPair # opt arg

$(PRINTF) "%s '%s'\n" "$1" '$2'

endef

define OptionTrip # opt arg arg

$(PRINTF) "%s '%s' '%s'\n" "$1" '$2' '$3'

endef

# Core api bottom argument (with special sauce)

COREAPI_BOTTOM = <font size="-1"> $(BUG_SUBMIT_LINE)\

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

see <a href="$(DEV_DOCS_URL)" 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.<br>\

$(call CopyrightLine,$(COPYRIGHT_URL),$(FIRST_COPYRIGHT_YEAR),)\

</font>

# Common javadoc options used by all

COMMON_JAVADOCFLAGS =					\

                $(NO_PROPRIETARY_API_WARNINGS)          \

		-quiet					\

                -use					\

                -keywords				\

		$(ADDITIONAL_JAVADOCFLAGS)

ifdef OPENJDK

  ADDITIONAL_JAVADOCFLAGS =				\

                -Xdocrootparent $(DOCS_BASE_URL)

else

  ADDITIONAL_JAVADOCFLAGS =

endif

# Draft used for non-fcs documents

JDK_IS_FCS = false

DRAFT_HEADER =

ifeq ($(JDK_MINOR_VERSION),5)

  JDK_IS_FCS = true

endif

ifeq ($(JDK_MINOR_VERSION),6)

  JDK_IS_FCS = true

endif

ifeq ($(JDK_MINOR_VERSION),7)

  JDK_IS_FCS = true

endif

ifeq ($(JDK_IS_FCS),false)

  ifneq ($(MILESTONE), fcs)

    DRAFT_HEADER = <br><strong>DRAFT&nbsp;$(MILESTONE)-$(BUILD_NUMBER)</strong>

    DRAFT_BOTTOM = <br><strong>DRAFT&nbsp;$(MILESTONE)-$(BUILD_NUMBER)</strong>

    DRAFT_WINTITLE = $(BUILD_NUMBER)

    # Early access top text (not used in FCS releases)

    COREAPI_TOP_EARLYACCESS = \

<div style="background-color: \#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

endif

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

#

# CORE_PKGS environment variable has been moved to the following file

#

include CORE_PKGS.gmk

#

# Load environment variables for API package names that are not part of

# the Java SE platform

#

include NON_CORE_PKGS.gmk

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

#

# Default target is same as docs target, create core api and all others it can

#

all: docs

docs: coredocs otherdocs

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

# Production Targets -- USE THESE TARGETS WHEN:

#    a) You're generating docs outside of release engineering's

#       standard control build.

#    b) The docs will be pushed to the web and/or included in

#       the downloaded doc bundle.

#

# See:  Notes.html#releaseTargets

# Note: Spaces precede ifdef/ifndef indents. Tabs precede target commands (!)

#

sanitycheckcoredocs:

	@$(ECHO) ""

	@$(ECHO) "Building core api docs with these values:"

	@$(ECHO) "    BUILD_NUMBER = $(BUILD_NUMBER)"

	@$(ECHO) "    MILESTONE = $(MILESTONE)"

	@$(ECHO) ""

  ifeq ($(BUILD_NUMBER), b00)

	@$(ECHO) "ERROR: Build number must be defined"

	@$(ECHO) "MILESTONE is set to $(MILESTONE)"

	@$(ECHO) ""

	exit 1

  endif

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

#

# coredocs

#

COREAPI_DOCTITLE  = Java$(TRADEMARK) Platform, Standard Edition \

$(JDK_MINOR_VERSION)<br>API Specification

COREAPI_WINDOWTITLE  = Java Platform SE $(JDK_MINOR_VERSION)

COREAPI_HEADER = \

<strong>Java$(TRADEMARK)&nbsp;Platform<br>Standard&nbsp;Ed.&nbsp;$(JDK_MINOR_VERSION)</strong>

# Java language specification cite

TAG_JLS = jls:a:See <cite> \

The Java&trade; Language Specification</cite>:

# Overview file for core apis

COREAPI_OVERVIEW = $(SHARE_SRC)/classes/overview-core.html

# The index.html, options, and packages files

COREAPI_INDEX_FILE    = $(COREAPI_DOCSDIR)/index.html

COREAPI_OPTIONS_FILE  = $(DOCSTMPDIR)/coredocs.options

COREAPI_PACKAGES_FILE = $(DOCSTMPDIR)/coredocs.packages

coredocs: $(COREAPI_INDEX_FILE)

# Set relative location to core api document root

$(COREAPI_INDEX_FILE): GET2DOCSDIR=..

# Run javadoc if the index file is out of date or missing

$(COREAPI_INDEX_FILE): $(COREAPI_OPTIONS_FILE) $(COREAPI_PACKAGES_FILE)

	$(prep-javadoc)

	$(call JavadocSummary,$(COREAPI_OPTIONS_FILE),$(COREAPI_PACKAGES_FILE))

	$(JAVADOC_CMD) $(JAVADOC_VM_MEMORY_FLAGS) -d $(@D) \

	  @$(COREAPI_OPTIONS_FILE) @$(COREAPI_PACKAGES_FILE)

# Create file with javadoc options in it

$(COREAPI_OPTIONS_FILE): $(COREAPI_OVERVIEW)

	$(prep-target)

	@($(call OptionOnly,$(COMMON_JAVADOCFLAGS))			; \

	  $(call OptionPair,-sourcepath,$(RELEASEDOCS_SOURCEPATH))	; \

	  $(call OptionPair,-encoding,ISO-8859-1)			; \

	  $(call OptionPair,-tag,beaninfo:X)				; \

	  $(call OptionPair,-tag,revised:X)				; \

	  $(call OptionPair,-tag,since.unbundled:X)			; \

	  $(call OptionPair,-tag,spec:X)				; \

	  $(call OptionPair,-tag,specdefault:X)				; \

	  $(call OptionPair,-tag,Note:X)				; \

	  $(call OptionPair,-tag,ToDo:X)				; \

          $(call OptionPair,-tag,$(TAG_JLS)) 				; \

	  $(call OptionOnly,-splitIndex)				; \

	  $(call OptionPair,-overview,$(COREAPI_OVERVIEW))		; \

	  $(call OptionPair,-doctitle,$(COREAPI_DOCTITLE))		; \

	  $(call OptionPair,-windowtitle,$(COREAPI_WINDOWTITLE) $(DRAFT_WINTITLE)) ;\

	  $(call OptionPair,-header,$(COREAPI_HEADER)$(DRAFT_HEADER))	; \

	  $(call OptionPair,-bottom,$(COREAPI_BOTTOM)$(DRAFT_BOTTOM))	; \

        ) >> $@

ifdef COREAPI_TOP_EARLYACCESS

	@$(call OptionPair,-top,$(COREAPI_TOP_EARLYACCESS)) >> $@

endif

# Create a file with the package names in it

$(COREAPI_PACKAGES_FILE): $(DIRECTORY_CACHE) $(call PackageDependencies,$(CORE_PKGS))

	$(prep-target)

	$(call PackageFilter,$(CORE_PKGS))

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

#

# mirrordocs

#

# Part of langtools

ifdef LANGTOOLS_DIST

  ALL_OTHER_TARGETS += mirrordocs

endif

MIRROR_DOCDIR      := $(JDK_API_DOCSDIR)/apt/mirror

MIRROR2COREAPI     := ../../$(JDKJRE2COREAPI)

MIRROR_DOCTITLE    := Mirror API

MIRROR_WINDOWTITLE := Mirror API

MIRROR_HEADER      := <strong>Mirror API</strong>

MIRROR_BOTTOM      := $(call CommonBottom,$(MIRROR_FIRST_COPYRIGHT_YEAR))

MIRROR_GROUPNAME   := Packages

MIRROR_OVERVIEW    := $(IMPORTSRCDIR)/com/sun/mirror/overview.html

MIRROR_REGEXP      := com.sun.mirror.*

# MIRROR_PKGS is located in NON_CORE_PKGS.gmk

# The index.html, options, and packages files

MIRROR_INDEX_FILE    = $(MIRROR_DOCDIR)/index.html

MIRROR_OPTIONS_FILE  = $(DOCSTMPDIR)/mirror.options

MIRROR_PACKAGES_FILE = $(DOCSTMPDIR)/mirror.packages

mirrordocs: $(MIRROR_INDEX_FILE)

# Set relative location to core api document root

$(MIRROR_INDEX_FILE): GET2DOCSDIR=$(MIRROR2COREAPI)/..

# Run javadoc if the index file is out of date or missing

$(MIRROR_INDEX_FILE): $(MIRROR_OPTIONS_FILE) $(MIRROR_PACKAGES_FILE)

	$(prep-javadoc)

	$(call JavadocSummary,$(MIRROR_OPTIONS_FILE),$(MIRROR_PACKAGES_FILE))

	$(JAVADOC_CMD) $(JAVADOC_VM_MEMORY_FLAGS) -d $(@D) \

	  @$(MIRROR_OPTIONS_FILE) @$(MIRROR_PACKAGES_FILE)

# Create file with javadoc options in it

$(MIRROR_OPTIONS_FILE): $(MIRROR_OVERVIEW)

	$(prep-target)

	@($(call OptionOnly,$(COMMON_JAVADOCFLAGS))			; \

	  $(call OptionPair,-sourcepath,$(RELEASEDOCS_SOURCEPATH))	; \

	  $(call OptionPair,-encoding,ascii)				; \

	  $(call OptionPair,-overview,$(MIRROR_OVERVIEW))		; \

	  $(call OptionPair,-doctitle,$(MIRROR_DOCTITLE))		; \

	  $(call OptionPair,-windowtitle,$(MIRROR_WINDOWTITLE) $(DRAFT_WINTITLE));\

	  $(call OptionPair,-header,$(MIRROR_HEADER)$(DRAFT_HEADER))	; \

	  $(call OptionPair,-bottom,$(MIRROR_BOTTOM)$(DRAFT_BOTTOM)) 	; \

	  $(call OptionTrip,-group,$(MIRROR_GROUPNAME),$(MIRROR_REGEXP)); \

	  $(call OptionTrip,-linkoffline,$(MIRROR2COREAPI),$(COREAPI_DOCSDIR)); \

        ) >> $@

# Create a file with the package names in it

$(MIRROR_PACKAGES_FILE): $(DIRECTORY_CACHE) $(call PackageDependencies,$(MIRROR_PKGS))

	$(prep-target)

	$(call PackageFilter,$(MIRROR_PKGS))

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

#

# docletapidocs

#

# Part of langtools

ifdef LANGTOOLS_DIST

  ALL_OTHER_TARGETS += docletapidocs

endif

DOCLETAPI_DOCDIR       := $(JDK_API_DOCSDIR)/javadoc/doclet

DOCLETAPI2COREAPI      := ../../$(JDKJRE2COREAPI)

DOCLETAPI_DOCTITLE     := Doclet API

DOCLETAPI_WINDOWTITLE  := Doclet API

DOCLETAPI_HEADER       := <strong>Doclet API</strong>

DOCLETAPI_BOTTOM       := $(call CommonTrademarkBottom,$(DOCLETAPI_FIRST_COPYRIGHT_YEAR))

DOCLETAPI_GROUPNAME    := Packages

DOCLETAPI_REGEXP       := com.sun.javadoc

# DOCLETAPI_PKGS is located in NON_CORE_PKGS.gmk

# The index.html, options, and packages files

DOCLETAPI_INDEX_FILE    = $(DOCLETAPI_DOCDIR)/index.html

DOCLETAPI_OPTIONS_FILE  = $(DOCSTMPDIR)/docletapi.options

DOCLETAPI_PACKAGES_FILE = $(DOCSTMPDIR)/docletapi.packages

docletapidocs: $(DOCLETAPI_INDEX_FILE)

# Set relative location to core api document root

$(DOCLETAPI_INDEX_FILE): GET2DOCSDIR=$(DOCLETAPI2COREAPI)/..

# Run javadoc if the index file is out of date or missing

$(DOCLETAPI_INDEX_FILE): $(DOCLETAPI_OPTIONS_FILE) $(DOCLETAPI_PACKAGES_FILE)

	$(prep-javadoc)

	$(call JavadocSummary,$(DOCLETAPI_OPTIONS_FILE),$(DOCLETAPI_PACKAGES_FILE))

	$(JAVADOC_CMD) $(JAVADOC_VM_MEMORY_FLAGS) -d $(@D) \

	  @$(DOCLETAPI_OPTIONS_FILE) @$(DOCLETAPI_PACKAGES_FILE)

# Create file with javadoc options in it

$(DOCLETAPI_OPTIONS_FILE):

	$(prep-target)

	@($(call OptionOnly,$(COMMON_JAVADOCFLAGS))			; \

	  $(call OptionPair,-sourcepath,$(RELEASEDOCS_SOURCEPATH))	; \

	  $(call OptionPair,-encoding,ascii)				; \

	  $(call OptionOnly,-breakiterator)				; \

	  $(call OptionPair,-doctitle,$(DOCLETAPI_DOCTITLE))		; \

	  $(call OptionPair,-windowtitle,$(DOCLETAPI_WINDOWTITLE) $(DRAFT_WINTITLE));\

	  $(call OptionPair,-header,$(DOCLETAPI_HEADER)$(DRAFT_HEADER))	; \

	  $(call OptionPair,-bottom,$(DOCLETAPI_BOTTOM)$(DRAFT_BOTTOM))	; \

	  $(call OptionTrip,-group,$(DOCLETAPI_GROUPNAME),$(DOCLETAPI_REGEXP)); \

	  $(call OptionTrip,-linkoffline,$(DOCLETAPI2COREAPI),$(COREAPI_DOCSDIR)/); \

        ) >> $@

# Create a file with the package names in it

$(DOCLETAPI_PACKAGES_FILE): $(DIRECTORY_CACHE) $(call PackageDependencies,$(DOCLETAPI_PKGS))

	$(prep-target)

	$(call PackageFilter,$(DOCLETAPI_PKGS))

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

#

# tagletapidocs

#

# Part of langtools

ifdef LANGTOOLS_DIST

  ALL_OTHER_TARGETS += tagletapidocs

endif

TAGLETAPI_DOCDIR   := $(JDK_API_DOCSDIR)/javadoc/taglet

TAGLETAPI2COREAPI  := ../../$(JDKJRE2COREAPI)

TAGLETAPI_BOTTOM   := $(call CommonTrademarkBottom,$(TAGLETAPI_FIRST_COPYRIGHT_YEAR))

# TAGLETAPI_FILE is located in NON_CORE_PKGS.gmk

# Temporary directory (special generation rules)

TAGLETAPI_TEMPDIR       = $(DOCSTMPDIR)/taglets_temp

# The index.html, options, and packages files

TAGLETAPI_INDEX_FILE    = $(TAGLETAPI_DOCDIR)/index.html

TAGLETAPI_OPTIONS_FILE  = $(DOCSTMPDIR)/tagletapi.options

TAGLETAPI_PACKAGES_FILE = $(DOCSTMPDIR)/tagletapi.packages