1 # Copyright (c) 1997, 2017, Oracle and/or its affiliates. All rights reserved.
   2 # DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   3 #
   4 # This code is free software; you can redistribute it and/or modify it
   5 # under the terms of the GNU General Public License version 2 only, as
   6 # published by the Free Software Foundation.  Oracle designates this
   7 # particular file as subject to the "Classpath" exception as provided
   8 # by Oracle in the LICENSE file that accompanied this code.
   9 #
  10 # This code is distributed in the hope that it will be useful, but WITHOUT
  11 # ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  12 # FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  13 # version 2 for more details (a copy is included in the LICENSE file that
  14 # accompanied this code).
  15 #
  16 # You should have received a copy of the GNU General Public License version
  17 # 2 along with this work; if not, write to the Free Software Foundation,
  18 # Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  19 #
  20 # Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  21 # or visit www.oracle.com if you need additional information or have any
  22 # questions.
  23 #
  24 
  25 default: all
  26 
  27 include $(SPEC)
  28 include MakeBase.gmk
  29 include Modules.gmk
  30 include ZipArchive.gmk
  31 include $(JDK_TOPDIR)/make/Tools.gmk
  32 include $(JDK_TOPDIR)/make/ModuleTools.gmk
  33 
  34 # This is needed to properly setup DOCS_MODULES.
  35 $(eval $(call ReadImportMetaData))
  36 
  37 ################################################################################
  38 # Javadoc settings
  39 
  40 # List of all possible directories for javadoc to look for sources
  41 # Allow custom to overwrite.
  42 JAVADOC_SOURCE_DIRS = \
  43       $(SUPPORT_OUTPUTDIR)/gensrc/* \
  44       $(addsuffix /*, $(IMPORT_MODULES_SRC)) \
  45       $(JDK_TOPDIR)/src/*/$(OPENJDK_TARGET_OS)/classes \
  46       $(JDK_TOPDIR)/src/*/$(OPENJDK_TARGET_OS_TYPE)/classes \
  47       $(JDK_TOPDIR)/src/*/share/classes \
  48       $(HOTSPOT_TOPDIR)/src/*/share/classes \
  49       $(LANGTOOLS_TOPDIR)/src/*/share/classes \
  50       $(NASHORN_TOPDIR)/src/*/share/classes \
  51       $(CORBA_TOPDIR)/src/*/share/classes \
  52       $(JAXP_TOPDIR)/src/*/share/classes \
  53       $(JAXWS_TOPDIR)/src/*/share/classes \
  54       $(SUPPORT_OUTPUTDIR)/rmic/* \
  55       $(JDK_TOPDIR)/src/*/share/doc/stub \
  56       #
  57 
  58 # All modules to have docs generated by docs-javadoc target
  59 JAVADOC_MODULES := $(sort $(DOCS_MODULES))
  60 
  61 # Should we use -Xdocrootparent? Allow custom to overwrite.
  62 DOCROOTPARENT_FLAG = TRUE
  63 
  64 # URLs
  65 JAVADOC_BASE_URL := http://docs.oracle.com/javase/$(VERSION_SPECIFICATION)/docs
  66 BUG_SUBMIT_URL := http://bugreport.java.com/bugreport/
  67 COPYRIGHT_URL := {@docroot}/../legal/cpyr.html
  68 
  69 # In order to get a specific ordering it's necessary to specify the total
  70 # ordering of tags as the tags are otherwise ordered in order of definition.
  71 JAVADOC_TAGS := \
  72     -tag beaninfo:X \
  73     -tag revised:X \
  74     -tag since.unbundled:X \
  75     -tag spec:X \
  76     -tag specdefault:X \
  77     -tag Note:X \
  78     -tag ToDo:X \
  79     -tag 'apiNote:a:API Note:' \
  80     -tag 'implSpec:a:Implementation Requirements:' \
  81     -tag 'implNote:a:Implementation Note:' \
  82     -tag param \
  83     -tag return \
  84     -tag throws \
  85     -taglet build.tools.taglet.ModuleGraph \
  86     -tag since \
  87     -tag version \
  88     -tag serialData \
  89     -tag factory \
  90     -tag see \
  91     -tag 'jvms:a:See <cite>The Java&trade; Virtual Machine Specification</cite>:' \
  92     -tag 'jls:a:See <cite>The Java&trade; Language Specification</cite>:' \
  93     -taglet build.tools.taglet.Incubating \
  94     -tagletpath $(BUILDTOOLS_OUTPUTDIR)/jdk_tools_classes \
  95     #
  96 
  97 # Which doclint checks to ignore
  98 JAVADOC_DISABLED_DOCLINT := accessibility html missing syntax reference
  99 
 100 # The initial set of options for javadoc
 101 JAVADOC_OPTIONS := -XDignore.symbol.file=true -use -keywords -notimestamp \
 102     -serialwarn -encoding ISO-8859-1 -breakiterator -splitIndex --system none \
 103     --expand-requires transitive
 104 
 105 #
 106 # TODO: this should be set by the configure option.
 107 #
 108 ifndef ENABLE_MODULE_GRAPH
 109    ENABLE_MODULE_GRAPH=false
 110 endif
 111 
 112 # Should we add DRAFT stamps to the generated javadoc?
 113 ifeq ($(VERSION_IS_GA), true)
 114   IS_DRAFT := false
 115 else
 116   IS_DRAFT := true
 117 endif
 118 
 119 ################################################################################
 120 # Text snippets
 121 
 122 FULL_COMPANY_NAME := Oracle and/or its affiliates
 123 COMPANY_ADDRESS := 500 Oracle Parkway<br>Redwood Shores, CA 94065 USA
 124 
 125 ifeq ($(IS_DRAFT), true)
 126   DRAFT_MARKER_STR := <br><strong>DRAFT $(VERSION_STRING)</strong>
 127   ifeq ($(VERSION_BUILD), 0)
 128     DRAFT_MARKER_TITLE := [ad-hoc build]
 129   else
 130     DRAFT_MARKER_TITLE := [build $(VERSION_BUILD)]
 131   endif
 132 endif
 133 
 134 JAVADOC_WINDOW_TITLE := Java Platform SE $(VERSION_SPECIFICATION) \
 135     $(DRAFT_MARKER_TITLE)
 136 
 137 JAVADOC_DOC_TITLE := Java&trade; Platform, Standard Edition \
 138     $(VERSION_SPECIFICATION)<br>API Specification
 139 
 140 JAVADOC_HEADER_TITLE := $(subst $(SPACE),&nbsp;,$(strip \
 141     <strong>Java&trade; Platform<br>Standard Ed. \
 142     $(VERSION_SPECIFICATION)</strong>$(DRAFT_MARKER_STR)))
 143 
 144 JAVADOC_BOTTOM := \
 145     <span style="font-size:smaller"> \
 146     <a href="$(BUG_SUBMIT_URL)">Submit a bug or feature</a><br> \
 147     For further API reference and developer documentation, see \
 148     <a href="$(JAVADOC_BASE_URL)/index.html" target="_blank">Java SE \
 149     Documentation</a>. That documentation contains more detailed, \
 150     developer-targeted descriptions, with conceptual overviews, definitions \
 151     of terms, workarounds, and working code examples.<br> \
 152     Java is a trademark or registered trademark of $(FULL_COMPANY_NAME) in \
 153     the US and other countries.<br> \
 154     <a href="$(COPYRIGHT_URL)">Copyright</a> \
 155     &copy; 1993, $(COPYRIGHT_YEAR), $(FULL_COMPANY_NAME). \
 156     $(COMPANY_ADDRESS). All rights reserved.$(DRAFT_MARKER_STR)</span>
 157 
 158 JAVADOC_TOP := \
 159       <div style="background-color: $(HASH)EEEEEE"><div style="padding: 6px; \
 160       margin-top: 2px; margin-bottom: 6px; margin-left: 6px; margin-right: \
 161       6px; text-align: justify; font-size: 80%; font-family: Helvetica, Arial, \
 162       sans-serif; font-weight: normal;">Please note that the specifications \
 163       and other information contained herein are not final and are subject to \
 164       change. The information is being made available to you solely for \
 165       purpose of evaluation.</div></div>
 166 
 167 ################################################################################
 168 # Setup call to javadoc based on above settings
 169 
 170 # Create a string like "-Xdoclint:all,-syntax,-html,..."
 171 JAVADOC_OPTIONS += -Xdoclint:all,$(call CommaList, $(addprefix -, \
 172     $(JAVADOC_DISABLED_DOCLINT)))
 173 
 174 ifneq ($($DOCROOTPARENT_FLAG), )
 175   JAVADOC_OPTIONS += -Xdocrootparent $(JAVADOC_BASE_URL)
 176 endif
 177 
 178 JAVADOC_OPTIONS += -doctitle '$(JAVADOC_DOC_TITLE)'
 179 JAVADOC_OPTIONS += -windowtitle '$(JAVADOC_WINDOW_TITLE)'
 180 JAVADOC_OPTIONS += -header '$(JAVADOC_HEADER_TITLE)'
 181 JAVADOC_OPTIONS += -bottom '$(JAVADOC_BOTTOM)'
 182 ifeq ($(IS_DRAFT), true)
 183   JAVADOC_OPTIONS += -top '$(JAVADOC_TOP)'
 184 endif
 185 
 186 # Do not store debug level options in VARDEPS.
 187 ifneq ($(LOG_LEVEL), trace)
 188   JAVADOC_LOG_OPTION += -quiet
 189 else
 190   JAVADOC_LOG_OPTION += -verbose
 191 endif
 192 
 193 JAVADOC_VARDEPS := $(JAVADOC_OPTIONS) $(JAVADOC_TAGS) $(JAVADOC_MODULES)
 194 JAVADOC_VARDEPS_FILE := $(call DependOnVariable, JAVADOC_VARDEPS, \
 195     $(SUPPORT_OUTPUTDIR)/docs/javadoc.vardeps)
 196 
 197 # Get a list of all files in all the source dirs for all included modules
 198 JAVADOC_SOURCE_DEPS := $(call CacheFind, $(wildcard \
 199     $(foreach module, $(JAVADOC_MODULES), $(call FindModuleSrcDirs, $(module)))))
 200 
 201 JAVADOC_TARGET_DIR := $(JAVADOC_OUTPUTDIR)/api
 202 JAVADOC_OVERVIEW := $(JDK_TOPDIR)/src/java.base/share/classes/overview-core.html
 203 
 204 # Javadoc creates a lot of files but use index.html as a marker
 205 $(JAVADOC_TARGET_DIR)/index.html: $(BUILD_TOOLS_JDK) $(JAVADOC_VARDEPS_FILE) \
 206     $(JAVADOC_SOURCE_DEPS) $(JAVADOC_OVERVIEW)
 207         $(call LogWarn, Generating Javadoc for $(words $(JAVADOC_MODULES)) modules)
 208         $(call LogInfo, Javadoc modules: $(JAVADOC_MODULES))
 209         $(call MakeDir, $(JAVADOC_TARGET_DIR))
 210         $(call ExecuteWithLog, $(SUPPORT_OUTPUTDIR)/docs/javadoc, \
 211             $(JAVA) -Djava.awt.headless=true \
 212                 -DenableModuleGraph=$(ENABLE_MODULE_GRAPH) \
 213                 $(NEW_JAVADOC) -d $(JAVADOC_TARGET_DIR) \
 214                 $(JAVADOC_TAGS) $(JAVADOC_OPTIONS) $(JAVADOC_LOG_OPTION) \
 215                 -overview $(JAVADOC_OVERVIEW) \
 216                 --module-source-path $(call PathList, $(JAVADOC_SOURCE_DIRS)) \
 217                 --module $(call CommaList, $(JAVADOC_MODULES)))
 218 
 219 JAVADOC_TARGETS += $(JAVADOC_TARGET_DIR)/index.html
 220 
 221 ################################################################################
 222 # Generate reference javadoc for Java SE
 223 
 224 REFERENCE_TARGET_DIR := $(SUPPORT_OUTPUTDIR)/javase-api
 225 REFERENCE_OVERVIEW := $(JDK_TOPDIR)/src/java.base/share/classes/overview-core.html
 226 
 227 # Javadoc creates a lot of files but use index.html as a marker.
 228 $(REFERENCE_TARGET_DIR)/index.html: $(BUILD_TOOLS_JDK) $(JAVADOC_VARDEPS_FILE) \
 229     $(JAVADOC_SOURCE_DEPS) $(REFERENCE_OVERVIEW)
 230         $(call LogWarn, Generating reference Javadoc for Java SE)
 231         $(call MakeDir, $(REFERENCE_TARGET_DIR))
 232         $(call ExecuteWithLog, $(SUPPORT_OUTPUTDIR)/docs/reference, \
 233             $(JAVA) -Djava.awt.headless=true \
 234                 -DenableModuleGraph=$(ENABLE_MODULE_GRAPH) \
 235                 $(NEW_JAVADOC) -d $(REFERENCE_TARGET_DIR) \
 236                 $(JAVADOC_TAGS) $(JAVADOC_OPTIONS) $(JAVADOC_LOG_OPTION) \
 237                 -overview $(REFERENCE_OVERVIEW) \
 238                 --module-source-path $(call PathList, $(JAVADOC_SOURCE_DIRS)) \
 239                 --module $(call CommaList, java.base java.se.ee))
 240 
 241 REFERENCE_TARGETS += $(REFERENCE_TARGET_DIR)/index.html
 242 
 243 ################################################################################
 244 # Copy targets
 245 
 246 JDWP_HTML := $(SUPPORT_OUTPUTDIR)/gensrc/jdk.jdi/jdwp-protocol.html
 247 
 248 $(eval $(call SetupCopyFiles, COPY_JDWP_HTML, \
 249     FILES := $(JDWP_HTML), \
 250     DEST := $(JAVADOC_OUTPUTDIR)/platform/jpda/jdwp, \
 251 ))
 252 
 253 COPY_TARGETS += $(COPY_JDWP_HTML)
 254 
 255 # Pick jvmti.html from any jvm variant, they are all the same.
 256 JVMTI_HTML := $(firstword \
 257     $(wildcard $(HOTSPOT_OUTPUTDIR)/variant-*/gensrc/jvmtifiles/jvmti.html))
 258 
 259 $(eval $(call SetupCopyFiles, COPY_JVMTI_HTML, \
 260     FILES := $(JVMTI_HTML), \
 261     DEST := $(JAVADOC_OUTPUTDIR)/platform/jvmti, \
 262 ))
 263 
 264 COPY_TARGETS += $(COPY_JVMTI_HTML)
 265 
 266 ################################################################################
 267 # Optional target which bundles all generated javadocs into a zip archive.
 268 
 269 JAVADOC_ZIP_NAME := jdk-$(VERSION_STRING)-docs.zip
 270 JAVADOC_ZIP_FILE := $(OUTPUT_ROOT)/bundles/$(JAVADOC_ZIP_NAME)
 271 
 272 $(eval $(call SetupZipArchive, BUILD_JAVADOC_ZIP, \
 273   SRC := $(JAVADOC_OUTPUTDIR), \
 274   ZIP := $(JAVADOC_ZIP_FILE), \
 275   EXTRA_DEPS := $(JAVADOC_TARGETS) $(COPY_TARGETS), \
 276 ))
 277 
 278 ZIP_TARGETS += $(BUILD_JAVADOC_ZIP)
 279 
 280 ################################################################################
 281 # generate .dot files for module graphs
 282 
 283 JAVADOC_MODULE_GRAPHS_DIR := $(SUPPORT_OUTPUTDIR)/docs/module-graphs
 284 JAVADOC_MODULE_GRAPHS := $(JAVADOC_MODULE_GRAPHS_DIR)/java.se.dot
 285 JAVADOC_MODULE_GRAPHS_PROPS := $(JDK_TOPDIR)/make/src/classes/build/tools/jigsaw/javadoc-graphs.properties
 286 
 287 $(JAVADOC_MODULE_GRAPHS): $(BUILD_JIGSAW_TOOLS) $(JAVADOC_MODULE_GRAPHS_PROPS)
 288         $(MKDIR) -p $(@D)
 289         $(TOOL_GENGRAPHS) --spec --output $(JAVADOC_MODULE_GRAPHS_DIR) \
 290             --dot-attributes $(JAVADOC_MODULE_GRAPHS_PROPS)
 291 
 292 MODULE_GRAPH_TARGETS += $(JAVADOC_MODULE_GRAPHS)
 293 
 294 ################################################################################
 295 
 296 # Hook to include the corresponding custom file, if present.
 297 $(eval $(call IncludeCustomExtension, , Javadoc.gmk))
 298 
 299 ################################################################################
 300 
 301 docs-module-graphs: $(MODULE_GRAPH_TARGETS)
 302 
 303 docs-javadoc: $(JAVADOC_TARGETS)
 304 
 305 docs-reference: $(REFERENCE_TARGETS)
 306 
 307 docs-copy: $(COPY_TARGETS)
 308 
 309 docs-zip: $(ZIP_TARGETS)
 310 
 311 all: docs-module-graphs docs-javadoc docs-reference docs-copy docs-zip
 312 
 313 .PHONY: default all docs-module-graphs docs-javadoc docs-reference docs-copy docs-zip