annotate make/Docs.gmk @ 2639:7df4f16bfa8f

8182408: Simplify the API-specification overview page Reviewed-by: erikj, mchung, jrose, alanb
author mr
date Mon, 19 Jun 2017 18:20:42 +0200
parents ce42e2c57dc7
children 985eae459953
rev   line source
ihse@2456 1 # Copyright (c) 1997, 2017, Oracle and/or its affiliates. All rights reserved.
ohair@476 2 # DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
ohair@476 3 #
ohair@476 4 # This code is free software; you can redistribute it and/or modify it
ohair@476 5 # under the terms of the GNU General Public License version 2 only, as
ohair@476 6 # published by the Free Software Foundation. Oracle designates this
ohair@476 7 # particular file as subject to the "Classpath" exception as provided
ohair@476 8 # by Oracle in the LICENSE file that accompanied this code.
ohair@476 9 #
ohair@476 10 # This code is distributed in the hope that it will be useful, but WITHOUT
ohair@476 11 # ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
ohair@476 12 # FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
ohair@476 13 # version 2 for more details (a copy is included in the LICENSE file that
ohair@476 14 # accompanied this code).
ohair@476 15 #
ohair@476 16 # You should have received a copy of the GNU General Public License version
ohair@476 17 # 2 along with this work; if not, write to the Free Software Foundation,
ohair@476 18 # Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
ohair@476 19 #
ohair@476 20 # Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
ohair@476 21 # or visit www.oracle.com if you need additional information or have any
ohair@476 22 # questions.
ohair@476 23 #
ohair@476 24
ihse@2325 25 default: all
ihse@2325 26
ohair@476 27 include $(SPEC)
ohair@476 28 include MakeBase.gmk
ihse@2572 29 include Modules.gmk
ihse@2590 30 include ProcessMarkdown.gmk
ihse@2572 31 include ZipArchive.gmk
chegar@2476 32 include $(JDK_TOPDIR)/make/Tools.gmk
mchung@2555 33 include $(JDK_TOPDIR)/make/ModuleTools.gmk
ohair@476 34
ihse@2572 35 # This is needed to properly setup DOCS_MODULES.
ihse@2572 36 $(eval $(call ReadImportMetaData))
ihse@2572 37
ihse@2325 38 ################################################################################
ihse@2584 39 # Hook to include the corresponding custom file, if present.
ihse@2608 40 $(eval $(call IncludeCustomExtension, , Docs.gmk))
ihse@2584 41
ihse@2584 42 ################################################################################
ihse@2624 43 # This file generates all documentation for OpenJDK.
ihse@2624 44 #
ihse@2624 45 # We will generate API documentation for two different selections of the source
ihse@2624 46 # code: "Java SE", which contains just the modules covered by the top-level
ihse@2624 47 # module java.se.ee, and "JDK", which covers all of Java SE and also all
ihse@2624 48 # other available modules that should be documented, including imported modules,
ihse@2624 49 # if any.
ihse@2624 50 #
ihse@2624 51 # We will also generate separate, free-standing specifications from either
ihse@2624 52 # markdown or existing html files.
ihse@2624 53 #
ihse@2624 54
ihse@2624 55 ################################################################################
ihse@2572 56 # Javadoc settings
ohair@476 57
ihse@2572 58 # On top of the sources that was used to compile the JDK, we need some
ihse@2572 59 # extra java.rmi sources that are used just for javadoc.
ihse@2573 60 MODULES_SOURCE_PATH := $(call PathList, $(call GetModuleSrcPath) \
ihse@2572 61 $(SUPPORT_OUTPUTDIR)/rmic/* $(JDK_TOPDIR)/src/*/share/doc/stub)
alanb@1970 62
ihse@2325 63 # URLs
ihse@2613 64 JAVADOC_BASE_URL := http://www.oracle.com/pls/topic/lookup?ctx=javase9&id=homepage
ihse@2325 65 BUG_SUBMIT_URL := http://bugreport.java.com/bugreport/
ihse@2636 66 COPYRIGHT_URL := {@docroot}/../legal/copyright.html
ihse@2597 67 LICENSE_URL := http://www.oracle.com/technetwork/java/javase/terms/license/java9speclicense.html
ihse@2597 68 REDISTRIBUTION_URL := http://www.oracle.com/technetwork/java/redist-137594.html
ihse@2597 69
ihse@2358 70 # In order to get a specific ordering it's necessary to specify the total
ihse@2358 71 # ordering of tags as the tags are otherwise ordered in order of definition.
ihse@2572 72 JAVADOC_TAGS := \
ihse@2358 73 -tag beaninfo:X \
ihse@2358 74 -tag revised:X \
ihse@2358 75 -tag since.unbundled:X \
ihse@2358 76 -tag spec:X \
ihse@2358 77 -tag specdefault:X \
ihse@2358 78 -tag Note:X \
ihse@2358 79 -tag ToDo:X \
ihse@2358 80 -tag 'apiNote:a:API Note:' \
ihse@2358 81 -tag 'implSpec:a:Implementation Requirements:' \
ihse@2358 82 -tag 'implNote:a:Implementation Note:' \
ihse@2358 83 -tag param \
ihse@2358 84 -tag return \
ihse@2358 85 -tag throws \
mchung@2555 86 -taglet build.tools.taglet.ModuleGraph \
ihse@2358 87 -tag since \
ihse@2358 88 -tag version \
ihse@2358 89 -tag serialData \
ihse@2358 90 -tag factory \
ihse@2358 91 -tag see \
ihse@2358 92 -tag 'jvms:a:See <cite>The Java&trade; Virtual Machine Specification</cite>:' \
ihse@2358 93 -tag 'jls:a:See <cite>The Java&trade; Language Specification</cite>:' \
ksrini@2583 94 -taglet build.tools.taglet.ExtLink \
chegar@2476 95 -taglet build.tools.taglet.Incubating \
chegar@2476 96 -tagletpath $(BUILDTOOLS_OUTPUTDIR)/jdk_tools_classes \
ihse@2584 97 $(CUSTOM_JAVADOC_TAGS) \
ihse@2358 98 #
ihse@2358 99
ihse@2572 100 # Which doclint checks to ignore
ihse@2572 101 JAVADOC_DISABLED_DOCLINT := accessibility html missing syntax reference
ihse@2572 102
ihse@2572 103 # The initial set of options for javadoc
ihse@2572 104 JAVADOC_OPTIONS := -XDignore.symbol.file=true -use -keywords -notimestamp \
ihse@2572 105 -serialwarn -encoding ISO-8859-1 -breakiterator -splitIndex --system none \
ihse@2586 106 -html5 -javafx --expand-requires transitive
ihse@2325 107
ihse@2572 108 # Should we add DRAFT stamps to the generated javadoc?
ihse@2572 109 ifeq ($(VERSION_IS_GA), true)
ihse@2572 110 IS_DRAFT := false
ihse@2572 111 else
ihse@2572 112 IS_DRAFT := true
ihse@2572 113 endif
ohair@476 114
ihse@2325 115 ################################################################################
ihse@2572 116 # General text snippets
alanb@1970 117
ihse@2572 118 FULL_COMPANY_NAME := Oracle and/or its affiliates
mr@2639 119 COMPANY_ADDRESS := 500 Oracle Parkway, Redwood Shores, CA 94065 USA
ohair@476 120
mr@2639 121 JAVA_PLATFORM := Java Platform
ihse@2624 122
ihse@2572 123 ifeq ($(IS_DRAFT), true)
ihse@2572 124 DRAFT_MARKER_STR := <br><strong>DRAFT $(VERSION_STRING)</strong>
ihse@2572 125 ifeq ($(VERSION_BUILD), 0)
ihse@2572 126 DRAFT_MARKER_TITLE := [ad-hoc build]
ihse@2572 127 else
ihse@2572 128 DRAFT_MARKER_TITLE := [build $(VERSION_BUILD)]
ihse@2572 129 endif
mr@2639 130 DRAFT_TEXT := This specification is not final and is subject to change. \
mr@2639 131 Use is subject to <a href="$(LICENSE_URL)">license terms</a>.
ihse@2572 132 endif
ihse@2572 133
ihse@2572 134 JAVADOC_BOTTOM := \
mr@2639 135 <a href="$(BUG_SUBMIT_URL)">Report a bug or suggest an enhancement</a><br> \
mr@2639 136 For further API reference and developer documentation see the \
ihse@2613 137 <a href="$(JAVADOC_BASE_URL)" target="_blank">Java SE \
mr@2639 138 Documentation</a>, which contains more detailed, \
mr@2639 139 developer-targeted descriptions with conceptual overviews, definitions \
ihse@2572 140 of terms, workarounds, and working code examples.<br> \
ihse@2572 141 Java is a trademark or registered trademark of $(FULL_COMPANY_NAME) in \
ihse@2572 142 the US and other countries.<br> \
ihse@2572 143 <a href="$(COPYRIGHT_URL)">Copyright</a> \
mr@2639 144 &copy; 1993, $(COPYRIGHT_YEAR), $(FULL_COMPANY_NAME), \
mr@2639 145 $(COMPANY_ADDRESS).<br>All rights reserved. \
mr@2639 146 Use is subject to <a href="$(LICENSE_URL)">license terms</a> and the \
ihse@2597 147 <a href="$(REDISTRIBUTION_URL)">documentation redistribution policy</a>. \
mr@2639 148 $(DRAFT_MARKER_STR) <!-- Version $(VERSION_STRING) -->
mr@2639 149
ihse@2572 150
ihse@2572 151 JAVADOC_TOP := \
mr@2639 152 <div style="padding: 6px; text-align: center; font-size: 80%; \
mr@2639 153 font-family: DejaVu Sans, Arial, Helvetica, sans-serif; \
mr@2639 154 font-weight: normal;">$(DRAFT_TEXT)</div>
ksrini@1899 155
ihse@2325 156 ################################################################################
ihse@2573 157 # JDK javadoc titles/text snippets
ksrini@1899 158
mr@2639 159 JDK_SHORT_NAME := Java SE $(VERSION_SPECIFICATION) &amp; JDK $(VERSION_SPECIFICATION)
mr@2639 160 JDK_LONG_NAME := Java<sup>&reg;</sup> Platform, Standard Edition \
mr@2639 161 <span style="white-space: nowrap;">&amp; Java Development Kit</span>
ihse@2573 162
ihse@2573 163 ################################################################################
ihse@2573 164 # Java SE javadoc titles/text snippets
ihse@2573 165
mr@2639 166 JAVASE_SHORT_NAME := Java SE $(VERSION_SPECIFICATION)
mr@2639 167 JAVASE_LONG_NAME := Java<sup>&reg;</sup> Platform, Standard Edition
ksrini@1899 168
ihse@2325 169 ################################################################################
ihse@2573 170 # Functions
alanb@1970 171
ihse@2573 172 # Helper function for creating a png file from a dot file generated by the
ihse@2573 173 # GenGraphs tool.
ihse@2573 174 # param 1: SetupJavadocGeneration namespace ($1)
ihse@2573 175 # param 2: module name
ihse@2573 176 #
ihse@2573 177 define setup_gengraph_dot_to_png
ihse@2573 178 $1_$2_DOT_SRC := $$($1_GENGRAPHS_DIR)/$2.dot
ihse@2573 179 $1_$2_PNG_TARGET := $$($1_TARGET_DIR)/$2-graph.png
ksrini@1899 180
ihse@2573 181 # For each module needing a graph, create a png file from the dot file
ihse@2573 182 # generated by the GenGraphs tool and store it in the target dir.
ihse@2573 183 $$($1_$2_PNG_TARGET): $$($1_GENGRAPHS_MARKER)
ihse@2573 184 $$(call MakeDir, $$(@D))
ihse@2573 185 $$(call ExecuteWithLog, $$($1_$2_DOT_SRC), \
ihse@2573 186 $$(DOT) -Tpng -o $$($1_$2_PNG_TARGET) $$($1_$2_DOT_SRC))
ihse@2572 187
ihse@2573 188 $1_MODULEGRAPH_TARGETS += $$($1_$2_PNG_TARGET)
ihse@2573 189 endef
ksrini@1899 190
ihse@2624 191 # Helper function to create the overview.html file to use with the -overview
ihse@2624 192 # javadoc option.
ihse@2624 193 # Returns the filename as $1_OVERVIEW.
ihse@2624 194 #
ihse@2624 195 # param 1: SetupJavadocGeneration namespace ($1)
ihse@2624 196 define create_overview_file
ihse@2624 197 $1_OVERVIEW_TEXT := \
ihse@2624 198 <!DOCTYPE html> \
ihse@2624 199 <html><head></head><body> \
ihse@2624 200 #
ihse@2624 201 ifneq ($$($1_GROUPS),)
ihse@2624 202 $1_OVERVIEW_TEXT += \
mr@2639 203 <p>This document is divided into \
mr@2639 204 $$(subst 2,two,$$(subst 3,three,$$(words $$($1_GROUPS)))) sections:</p> \
mr@2639 205 <blockquote><dl> \
mr@2639 206 #
ihse@2624 207 $1_OVERVIEW_TEXT += $$(foreach g, $$($1_GROUPS), \
mr@2639 208 <dt style="margin-top: 8px;"><a href="\#$$g">$$($$g_GROUP_NAME)</a></dt> \
mr@2639 209 <dd style="margin-top: 8px;">$$($$g_GROUP_DESCRIPTION)</dt> \
ihse@2624 210 )
ihse@2624 211 $1_OVERVIEW_TEXT += \
mr@2639 212 </dl><blockquote> \
ihse@2624 213 #
ihse@2624 214 endif
ihse@2624 215 $1_OVERVIEW_TEXT += \
ihse@2624 216 </body></html> \
ihse@2624 217 #
ihse@2624 218
ihse@2624 219 $1_OVERVIEW := $$(SUPPORT_OUTPUTDIR)/docs/$1-overview.html
ihse@2624 220
ihse@2624 221 $1_OVERVIEW_VARDEPS_FILE := $$(call DependOnVariable, $1_OVERVIEW_TEXT, \
ihse@2624 222 $$($1_OVERVIEW).vardeps)
ihse@2624 223
ihse@2624 224 $$($1_OVERVIEW): $$($1_OVERVIEW_VARDEPS_FILE)
ihse@2624 225 $$(call LogInfo, Creating overview.html for $1)
ihse@2624 226 $$(call MakeDir, $$(@D))
ihse@2624 227 $$(PRINTF) > $$@ '$$($1_OVERVIEW_TEXT)'
ihse@2624 228 endef
ihse@2624 229
ihse@2325 230 ################################################################################
ihse@2624 231 # Setup make rules to create an API documentation collection, using javadoc and
ihse@2624 232 # other tools if needed.
ihse@2573 233 #
ihse@2573 234 # Parameter 1 is the name of the rule. This name is used as variable prefix.
ihse@2573 235 # Targets generated are returned as $1_JAVADOC_TARGETS and
ihse@2573 236 # $1_MODULEGRAPH_TARGETS. Note that the index.html file will work as a "touch
ihse@2573 237 # file" for all the magnitude of files that are generated by javadoc.
ihse@2573 238 #
ihse@2573 239 # Remaining parameters are named arguments. These include:
ihse@2573 240 # MODULES - Modules to generate javadoc for
ihse@2624 241 # GROUPS - Name of the groups to divide the modules into, if any
ihse@2624 242 # SHORT_NAME - The short name of this documentation collection
ihse@2624 243 # LONG_NAME - The long name of this documentation collection
ihse@2573 244 # TARGET_DIR - Where to store the output
ihse@2573 245 #
ihse@2573 246 SetupApiDocsGeneration = $(NamedParamsMacroTemplate)
ihse@2573 247 define SetupApiDocsGenerationBody
ksrini@1899 248
ihse@2621 249 # Figure out all modules, both specified and transitive indirect exports, that
ihse@2621 250 # will be processed by javadoc.
ihse@2621 251 $1_INDIRECT_EXPORTS := $$(call FindTransitiveIndirectDepsForModules, $$($1_MODULES))
ihse@2621 252 $1_ALL_MODULES := $$(sort $$($1_MODULES) $$($1_INDIRECT_EXPORTS))
ksrini@1899 253
ihse@2573 254 ifeq ($$(ENABLE_FULL_DOCS), true)
ihse@2573 255 # Tell the ModuleGraph taglet to generate html links to soon-to-be-created
ihse@2573 256 # png files with module graphs.
ihse@2573 257 $1_JAVA_ARGS += -DenableModuleGraph=true
ihse@2573 258 endif
ihse@2572 259
ihse@2573 260 # Always include tags and basic options
ihse@2573 261 $1_OPTIONS := $$(JAVADOC_TAGS) $$(JAVADOC_OPTIONS)
ihse@2572 262
ihse@2573 263 $1_OPTIONS += --module-source-path $$(MODULES_SOURCE_PATH)
ihse@2573 264 $1_OPTIONS += --module $$(call CommaList, $$($1_MODULES))
ihse@2572 265
ihse@2573 266 # Create a string like "-Xdoclint:all,-syntax,-html,..."
ihse@2573 267 $1_OPTIONS += -Xdoclint:all,$$(call CommaList, $$(addprefix -, \
ihse@2573 268 $$(JAVADOC_DISABLED_DOCLINT)))
ihse@2573 269
mr@2639 270 $1_DOC_TITLE := $$($1_LONG_NAME)<br>Version $$(VERSION_SPECIFICATION) API Specification
mr@2639 271 $1_WINDOW_TITLE := $$(subst &amp;,&,$$($1_SHORT_NAME)) \
ihse@2624 272 $$(DRAFT_MARKER_TITLE)
mr@2639 273 ifeq ($(VERSION_IS_GA), true) # Workaround stylesheet bug
mr@2639 274 $1_HEADER_PAD := 14
mr@2639 275 else
mr@2639 276 $1_HEADER_PAD := 9
mr@2639 277 endif
mr@2639 278 $1_HEADER_TITLE := <div style="margin-top: $$($1_HEADER_PAD)px;"><strong>$$($1_SHORT_NAME)</strong> \
mr@2639 279 $$(DRAFT_MARKER_STR)</div>
ihse@2624 280
ihse@2573 281 $1_OPTIONS += -doctitle '$$($1_DOC_TITLE)'
ihse@2573 282 $1_OPTIONS += -windowtitle '$$($1_WINDOW_TITLE)'
ihse@2573 283 $1_OPTIONS += -header '$$($1_HEADER_TITLE)'
ihse@2624 284 $1_OPTIONS += -bottom '$$(JAVADOC_BOTTOM)'
ihse@2573 285 ifeq ($$(IS_DRAFT), true)
ihse@2624 286 $1_OPTIONS += -top '$$(JAVADOC_TOP)'
ihse@2573 287 endif
ihse@2573 288
ihse@2573 289 # Do not store debug level options in VARDEPS.
ihse@2573 290 ifneq ($$(LOG_LEVEL), trace)
ihse@2573 291 $1_LOG_OPTION += -quiet
ihse@2573 292 else
ihse@2573 293 $1_LOG_OPTION += -verbose
ihse@2573 294 endif
ihse@2573 295
ihse@2624 296 # Generate the overview.html file. This will return the filename in
ihse@2624 297 # $1_OVERVIEW.
ihse@2624 298 $$(eval $$(call create_overview_file,$1))
ihse@2624 299 $1_OPTIONS += -overview $$($1_OVERVIEW)
ihse@2624 300
ihse@2624 301 $$(foreach g, $$($1_GROUPS), \
ihse@2624 302 $$(eval $1_OPTIONS += -group "$$($$g_GROUP_NAME)" "$$($$g_GROUP_MODULES)") \
ihse@2624 303 )
ihse@2624 304
ihse@2573 305 $1_VARDEPS := $$($1_JAVA_ARGS) $$($1_OPTIONS) $$(MODULES_SOURCE_PATH) \
ihse@2573 306 $$($1_ALL_MODULES)
ihse@2573 307 $1_VARDEPS_FILE := $$(call DependOnVariable, $1_VARDEPS, \
ihse@2573 308 $$(SUPPORT_OUTPUTDIR)/docs/$1.vardeps)
ihse@2573 309
ihse@2573 310 # Get a list of all files in all the source dirs for all included modules
ihse@2573 311 $1_SOURCE_DEPS := $$(call CacheFind, $$(wildcard $$(foreach module, \
ihse@2573 312 $$($1_ALL_MODULES), $$(call FindModuleSrcDirs, $$(module)))))
ihse@2573 313
ihse@2573 314 # Javadoc creates a lot of files but use index.html as a marker
ihse@2573 315 $$($1_TARGET_DIR)/index.html: $$(BUILD_TOOLS_JDK) $$($1_VARDEPS_FILE) \
ihse@2573 316 $$($1_SOURCE_DEPS) $$($1_OVERVIEW)
ihse@2624 317 $$(call LogWarn, Generating $1 javadoc for \
ihse@2573 318 $$(words $$($1_ALL_MODULES)) modules)
ihse@2573 319 $$(call LogInfo, Javadoc modules: $$($1_ALL_MODULES))
ihse@2573 320 $$(call MakeDir, $$($1_TARGET_DIR))
ihse@2573 321 $$(call ExecuteWithLog, $$(SUPPORT_OUTPUTDIR)/docs/$1, \
ihse@2573 322 $$(JAVA) -Djava.awt.headless=true $$($1_JAVA_ARGS) \
ihse@2573 323 $$(NEW_JAVADOC) -d $$($1_TARGET_DIR) \
ihse@2573 324 $$(JAVADOC_TAGS) $$($1_OPTIONS) $$($1_LOG_OPTION))
ihse@2573 325
ihse@2573 326 $1_JAVADOC_TARGETS := $$($1_TARGET_DIR)/index.html
ihse@2573 327
ihse@2573 328 ifeq ($$(ENABLE_FULL_DOCS), true)
ihse@2573 329 # We have asked ModuleGraph to generate links to png files. Now we must
ihse@2573 330 # produce the png files.
ihse@2573 331
ihse@2573 332 # Locate which modules has the @moduleGraph tag in their module-info.java
ihse@2573 333 $1_MODULES_NEEDING_GRAPH := $$(strip $$(foreach m, $$($1_ALL_MODULES), \
ihse@2573 334 $$(if $$(shell $$(GREP) -e @moduleGraph \
ihse@2573 335 $$(wildcard $$(addsuffix /module-info.java, \
ihse@2573 336 $$(call FindModuleSrcDirs, $$m)))), \
ihse@2573 337 $$m) \
ihse@2573 338 ))
ihse@2573 339
ihse@2573 340 # First we run the GenGraph tool. It will query the module structure of the
ihse@2573 341 # running JVM and output .dot files for all existing modules.
ihse@2573 342 GENGRAPHS_PROPS := \
ihse@2573 343 $$(JDK_TOPDIR)/make/src/classes/build/tools/jigsaw/javadoc-graphs.properties
ihse@2573 344
ihse@2573 345 $1_GENGRAPHS_DIR := $$(SUPPORT_OUTPUTDIR)/docs/$1-gengraphs
ihse@2573 346 $1_GENGRAPHS_MARKER := $$($1_GENGRAPHS_DIR)/_gengraphs_run.marker
ihse@2573 347
ihse@2573 348 $$($1_GENGRAPHS_MARKER): $$(BUILD_JIGSAW_TOOLS) $$(GENGRAPHS_PROPS)
ihse@2624 349 $$(call LogInfo, Running gengraphs for $1 documentation)
ihse@2573 350 $$(call MakeDir, $$($1_GENGRAPHS_DIR))
ihse@2573 351 $$(call ExecuteWithLog, $$($1_GENGRAPHS_DIR)/gengraphs, \
ihse@2573 352 $$(TOOL_GENGRAPHS) --spec --output $$($1_GENGRAPHS_DIR) \
ihse@2573 353 --dot-attributes $$(GENGRAPHS_PROPS) && \
ihse@2573 354 $$(TOUCH) $$($1_GENGRAPHS_MARKER))
ihse@2573 355
ihse@2573 356 # For each module needing a graph, create a png file from the dot file
ihse@2573 357 # generated by the GenGraphs tool and store it in the target dir.
ihse@2573 358 # They will depend on $1_GENGRAPHS_MARKER, and will be added to $1.
ihse@2573 359 $$(foreach m, $$($1_MODULES_NEEDING_GRAPH), \
ihse@2573 360 $$(eval $$(call setup_gengraph_dot_to_png,$1,$$m)) \
ihse@2573 361 )
ihse@2573 362 endif
ihse@2573 363 endef
ihse@2573 364
ihse@2573 365 ################################################################################
ihse@2573 366 # Setup generation of the JDK API documentation (javadoc + modulegraph)
ihse@2573 367
ihse@2624 368 # Define the groups of the JDK API documentation
ihse@2624 369 JavaSE_GROUP_NAME := Java SE
ihse@2624 370 JavaSE_GROUP_MODULES := $(call ColonList, $(sort java.se.ee \
ihse@2624 371 $(call FindTransitiveIndirectDepsForModules, java.se.ee)))
ihse@2624 372 JavaSE_GROUP_DESCRIPTION := \
mr@2639 373 The Java Platform, Standard Edition (Java SE) APIs define the core Java \
mr@2639 374 platform for general-purpose computing. These APIs are in modules whose \
mr@2639 375 names start with {@code java}. \
ihse@2624 376 #
ihse@2624 377 JDK_GROUPS += JavaSE
ihse@2624 378
ihse@2624 379 JDK_GROUP_NAME := JDK
ihse@2624 380 JDK_GROUP_MODULES := jdk.*
ihse@2624 381 JDK_GROUP_DESCRIPTION := \
mr@2639 382 The Java Development Kit (JDK) APIs are specific to the JDK and will not \
mr@2639 383 necessarily be available in all implementations of the Java SE Platform. \
mr@2639 384 These APIs are in modules whose names start with {@code jdk}. \
ihse@2624 385 #
ihse@2624 386 JDK_GROUPS += JDK
ihse@2624 387
ihse@2624 388 # If we are importing JavaFX, we need a JavaFX group. In an ideal world, this
ihse@2624 389 # would have been abstracted away to a more proper generic handling of imported
ihse@2624 390 # modules.
ihse@2624 391 ifneq ($(findstring javafx., $(IMPORTED_MODULES)), )
ihse@2624 392 JavaFX_GROUP_NAME := JavaFX
ihse@2624 393 JavaFX_GROUP_MODULES := javafx.*
ihse@2624 394 JavaFX_GROUP_DESCRIPTION := \
mr@2639 395 The JavaFX APIs define a set of user-interface controls, graphics, \
ihse@2624 396 media, and web packages for developing rich client applications. These \
mr@2639 397 APIs are in modules whose names start with {@code javafx}. \
ihse@2624 398 #
ihse@2624 399 JDK_GROUPS += JavaFX
ihse@2624 400 endif
ihse@2624 401
ihse@2573 402 # All modules to have docs generated by docs-jdk-api target
ihse@2624 403 JDK_MODULES := $(sort $(DOCS_MODULES))
ihse@2573 404
ihse@2573 405 $(eval $(call SetupApiDocsGeneration, JDK_API, \
ihse@2624 406 MODULES := $(JDK_MODULES), \
ihse@2624 407 GROUPS := $(JDK_GROUPS), \
ihse@2624 408 SHORT_NAME := $(JDK_SHORT_NAME), \
ihse@2624 409 LONG_NAME := $(JDK_LONG_NAME), \
ihse@2608 410 TARGET_DIR := $(DOCS_OUTPUTDIR)/api, \
ihse@2573 411 ))
ihse@2573 412
ihse@2573 413 # Targets generated are returned in JDK_API_JAVADOC_TARGETS and
ihse@2573 414 # JDK_API_MODULEGRAPH_TARGETS.
ihse@2573 415
ihse@2573 416 ################################################################################
ihse@2573 417 # Setup generation of the Java SE API documentation (javadoc + modulegraph)
ihse@2573 418
mr@2639 419 # The Java SE module scope is just java.se.ee and its transitive indirect
ihse@2621 420 # exports.
ihse@2624 421 JAVASE_MODULES := java.se.ee
ihse@2573 422
ihse@2573 423 $(eval $(call SetupApiDocsGeneration, JAVASE_API, \
ihse@2624 424 MODULES := $(JAVASE_MODULES), \
ihse@2624 425 SHORT_NAME := $(JAVASE_SHORT_NAME), \
ihse@2624 426 LONG_NAME := $(JAVASE_LONG_NAME), \
ihse@2573 427 TARGET_DIR := $(IMAGES_OUTPUTDIR)/javase-docs/api, \
ihse@2573 428 ))
ihse@2573 429
ihse@2573 430 # Targets generated are returned in JAVASE_API_JAVADOC_TARGETS and
ihse@2573 431 # JAVASE_API_MODULEGRAPH_TARGETS.
ohair@476 432
ihse@2325 433 ################################################################################
mchung@2610 434
ihse@2617 435 JDK_INDEX_HTML := $(DOCS_OUTPUTDIR)/index.html
mchung@2610 436
mchung@2633 437 JDK_INDEX_CONTENT := \
mchung@2633 438 <!DOCTYPE html> \
mchung@2633 439 <html lang="en"> \
mchung@2633 440 <head> \
mchung@2633 441 <meta http-equiv="refresh" content="0;url=api/index.html"> \
mchung@2633 442 </head> \
mchung@2633 443 </html>
mchung@2633 444
mchung@2633 445 $(JDK_INDEX_HTML):
mchung@2633 446 $(ECHO) '$(JDK_INDEX_CONTENT)' > $@
mchung@2610 447
ihse@2636 448 JDK_INDEX_TARGETS += $(JDK_INDEX_HTML)
ihse@2617 449
ihse@2617 450 # Copy the global resources
ihse@2617 451 GLOBAL_SPECS_RESOURCES_DIR := $(JDK_TOPDIR)/make/data/docs-resources/
ihse@2617 452 $(eval $(call SetupCopyFiles, COPY_GLOBAL_RESOURCES, \
ihse@2617 453 SRC := $(GLOBAL_SPECS_RESOURCES_DIR), \
ihse@2617 454 FILES := $(call CacheFind, $(GLOBAL_SPECS_RESOURCES_DIR)), \
ihse@2617 455 DEST := $(DOCS_OUTPUTDIR), \
ihse@2617 456 ))
ihse@2617 457 JDK_INDEX_TARGETS += $(COPY_GLOBAL_RESOURCES)
mchung@2610 458
mchung@2610 459 ################################################################################
ihse@2580 460 # Copy JDK specs files
ihse@2325 461
ihse@2580 462 # For all html documentation in $module/share/specs directories, copy it
ihse@2580 463 # unmodified
ihse@2325 464
ihse@2580 465 ALL_MODULES := $(call FindAllModules)
ihse@2590 466 COPY_SPEC_FILTER := %.html %.gif %.jpg %.mib %.css
ihse@2580 467
ihse@2580 468 $(foreach m, $(ALL_MODULES), \
ihse@2580 469 $(eval SPECS_$m := $(call FindModuleSpecsDirs, $m)) \
ihse@2600 470 $(foreach d, $(SPECS_$m), \
ihse@2600 471 $(if $(filter $(COPY_SPEC_FILTER), $(call CacheFind, $d)), \
ihse@2600 472 $(eval $(call SetupCopyFiles, COPY_$m, \
ihse@2600 473 SRC := $d, \
ihse@2600 474 FILES := $(filter $(COPY_SPEC_FILTER), $(call CacheFind, $d)), \
ihse@2608 475 DEST := $(DOCS_OUTPUTDIR)/specs/, \
ihse@2600 476 )) \
ihse@2600 477 $(eval JDK_SPECS_TARGETS += $(COPY_$m)) \
ihse@2600 478 ) \
ihse@2580 479 ) \
ihse@2580 480 )
ihse@2580 481
ihse@2581 482 ifeq ($(ENABLE_FULL_DOCS), true)
ihse@2581 483 # For all markdown files in $module/share/specs directories, convert them to
ihse@2581 484 # html.
ihse@2581 485
ihse@2617 486 GLOBAL_SPECS_DEFAULT_CSS_FILE := $(DOCS_OUTPUTDIR)/resources/jdk-default.css
ihse@2581 487
ihse@2581 488 $(foreach m, $(ALL_MODULES), \
ihse@2581 489 $(eval SPECS_$m := $(call FindModuleSpecsDirs, $m)) \
ihse@2590 490 $(foreach d, $(SPECS_$m), \
ihse@2590 491 $(if $(filter %.md, $(call CacheFind, $d)), \
ihse@2596 492 $(eval $(call SetupProcessMarkdown, CONVERT_MARKDOWN_$m_$(patsubst $(TOPDIR)/%,%,$d), \
ihse@2590 493 SRC := $d, \
ihse@2590 494 FILES := $(filter %.md, $(call CacheFind, $d)), \
ihse@2608 495 DEST := $(DOCS_OUTPUTDIR)/specs/, \
ihse@2590 496 CSS := $(GLOBAL_SPECS_DEFAULT_CSS_FILE), \
ihse@2590 497 )) \
ihse@2590 498 ) \
ihse@2596 499 $(eval JDK_SPECS_TARGETS += $(CONVERT_MARKDOWN_$m_$(patsubst $(TOPDIR)/%,%,$d))) \
ihse@2581 500 ) \
ihse@2581 501 )
ihse@2581 502 endif
ihse@2581 503
ihse@2580 504 # Special treatment for generated documentation
ihse@2580 505
ihse@2580 506 JDWP_PROTOCOL := $(SUPPORT_OUTPUTDIR)/gensrc/jdk.jdi/jdwp-protocol.html
ihse@2580 507 $(eval $(call SetupCopyFiles, COPY_JDWP_PROTOCOL, \
ihse@2580 508 FILES := $(JDWP_PROTOCOL), \
ihse@2608 509 DEST := $(DOCS_OUTPUTDIR)/specs/jdwp, \
ihse@2325 510 ))
ihse@2580 511 JDK_SPECS_TARGETS += $(COPY_JDWP_PROTOCOL)
ihse@2325 512
ihse@2580 513 # Get jvmti.html from the main jvm variant (all variants' jvmti.html are identical).
ihse@2580 514 JVMTI_HTML := $(HOTSPOT_OUTPUTDIR)/variant-$(JVM_VARIANT_MAIN)/gensrc/jvmtifiles/jvmti.html
erikj@2288 515 $(eval $(call SetupCopyFiles, COPY_JVMTI_HTML, \
erikj@2288 516 FILES := $(JVMTI_HTML), \
ihse@2608 517 DEST := $(DOCS_OUTPUTDIR)/specs, \
erikj@2288 518 ))
ihse@2580 519 JDK_SPECS_TARGETS += $(COPY_JVMTI_HTML)
ohair@476 520
ihse@2325 521 ################################################################################
ihse@2325 522 # Optional target which bundles all generated javadocs into a zip archive.
neugens@2031 523
ihse@2572 524 JAVADOC_ZIP_NAME := jdk-$(VERSION_STRING)-docs.zip
ihse@2572 525 JAVADOC_ZIP_FILE := $(OUTPUT_ROOT)/bundles/$(JAVADOC_ZIP_NAME)
ihse@2325 526
ihse@2572 527 $(eval $(call SetupZipArchive, BUILD_JAVADOC_ZIP, \
ihse@2608 528 SRC := $(DOCS_OUTPUTDIR), \
ihse@2580 529 ZIP := $(JAVADOC_ZIP_FILE), \
ihse@2580 530 EXTRA_DEPS := $(JDK_API_JAVADOC_TARGETS) $(JDK_API_MODULEGRAPH_TARGETS) \
ihse@2580 531 $(JDK_SPECS_TARGETS), \
ihse@2572 532 ))
neugens@2031 533
ihse@2572 534 ZIP_TARGETS += $(BUILD_JAVADOC_ZIP)
erikj@2177 535
erikj@2177 536 ################################################################################
erikj@2177 537
ihse@2608 538 docs-jdk-api-javadoc: $(JDK_API_JAVADOC_TARGETS) $(JDK_API_CUSTOM_TARGETS)
mchung@2555 539
ihse@2573 540 docs-jdk-api-modulegraph: $(JDK_API_MODULEGRAPH_TARGETS)
ihse@2572 541
ihse@2608 542 docs-javase-api-javadoc: $(JAVASE_API_JAVADOC_TARGETS) $(JAVASE_API_CUSTOM_TARGETS)
ihse@2573 543
ihse@2573 544 docs-javase-api-modulegraph: $(JAVASE_API_MODULEGRAPH_TARGETS)
ihse@2325 545
ihse@2580 546 docs-jdk-specs: $(JDK_SPECS_TARGETS)
ihse@2325 547
ihse@2617 548 docs-jdk-index: $(JDK_INDEX_TARGETS)
mchung@2610 549
ihse@2325 550 docs-zip: $(ZIP_TARGETS)
ihse@2325 551
ihse@2573 552 all: docs-jdk-api-javadoc docs-jdk-api-modulegraph docs-javase-api-javadoc \
mchung@2610 553 docs-javase-api-modulegraph docs-jdk-specs docs-jdk-index docs-zip
ihse@2325 554
ihse@2573 555 .PHONY: default all docs-jdk-api-javadoc docs-jdk-api-modulegraph \
mchung@2610 556 docs-javase-api-javadoc docs-javase-api-modulegraph docs-jdk-specs \
mchung@2610 557 docs-jdk-index docs-zip