< prev index next >

make/Docs.gmk

Print this page


   1 # Copyright (c) 1997, 2019, 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 Execute.gmk
  30 include Modules.gmk
  31 include ModuleTools.gmk
  32 include ProcessMarkdown.gmk
  33 include ToolsJdk.gmk
  34 include ZipArchive.gmk
  35 include TextFileProcessing.gmk

  36 
  37 # This is needed to properly setup DOCS_MODULES.
  38 $(eval $(call ReadImportMetaData))
  39 
  40 ################################################################################
  41 # Hook to include the corresponding custom file, if present.
  42 $(eval $(call IncludeCustomExtension, Docs.gmk))
  43 
  44 ################################################################################
  45 # This file generates all documentation for OpenJDK.
  46 #
  47 # We will generate API documentation for two different selections of the source
  48 # code: "Java SE", which contains just the modules covered by the top-level
  49 # module java.se and "JDK", which covers all of Java SE and also all
  50 # other available modules that should be documented, including imported modules,
  51 # if any.
  52 #
  53 # We will also generate separate, free-standing specifications from either
  54 # markdown or existing html files.
  55 #
  56 
  57 ################################################################################
  58 # Javadoc settings
  59 
  60 # On top of the sources that was used to compile the JDK, we need some
  61 # extra java.rmi sources that are used just for javadoc.
  62 MODULES_SOURCE_PATH := $(call PathList, $(call GetModuleSrcPath) \
  63     $(SUPPORT_OUTPUTDIR)/rmic/* $(TOPDIR)/src/*/share/doc/stub)
  64 
  65 # URLs
  66 JAVADOC_BASE_URL := https://docs.oracle.com/pls/topic/lookup?ctx=javase$(VERSION_NUMBER)&amp;id=homepage
  67 BUG_SUBMIT_URL := https://bugreport.java.com/bugreport/
  68 COPYRIGHT_URL := legal/copyright.html
  69 LICENSE_URL := https://www.oracle.com/technetwork/java/javase/terms/license/java$(VERSION_NUMBER)speclicense.html
  70 REDISTRIBUTION_URL := https://www.oracle.com/technetwork/java/redist-137594.html
  71 
  72 # In order to get a specific ordering it's necessary to specify the total
  73 # ordering of tags as the tags are otherwise ordered in order of definition.
  74 JAVADOC_TAGS := \
  75     -tag beaninfo:X \
  76     -tag revised:X \
  77     -tag since.unbundled:X \
  78     -tag spec:X \
  79     -tag specdefault:X \
  80     -tag Note:X \
  81     -tag ToDo:X \
  82     -tag 'apiNote:a:API Note:' \
  83     -tag 'implSpec:a:Implementation Requirements:' \
  84     -tag 'implNote:a:Implementation Note:' \
  85     -tag param \
  86     -tag return \
  87     -tag throws \
  88     -taglet build.tools.taglet.JSpec\$$JLS \
  89     -taglet build.tools.taglet.JSpec\$$JVMS \
  90     -taglet build.tools.taglet.ModuleGraph \
  91     -taglet build.tools.taglet.ToolGuide \
  92     -tag since \
  93     -tag serialData \
  94     -tag factory \
  95     -tag see \


  96     -taglet build.tools.taglet.ExtLink \
  97     -taglet build.tools.taglet.Incubating \
  98     -tagletpath $(BUILDTOOLS_OUTPUTDIR)/jdk_tools_classes \
  99     $(CUSTOM_JAVADOC_TAGS) \
 100     #
 101 
 102 # The reference tags must stay stable to allow for comparisons across the
 103 # development cycle. If JAVADOC_TAGS needs to change, make sure that
 104 # REFERENCE_TAGS remains unchanged, by copying and hardcoding, if necessary.
 105 REFERENCE_TAGS := $(JAVADOC_TAGS)
 106 
 107 # Which doclint checks to ignore
 108 JAVADOC_DISABLED_DOCLINT := accessibility html missing syntax reference
 109 
 110 # The initial set of options for javadoc
 111 JAVADOC_OPTIONS := -use -keywords -notimestamp \
 112     -serialwarn -encoding ISO-8859-1 -docencoding UTF-8 -breakiterator \
 113     -splitIndex --system none -javafx --expand-requires transitive \
 114     --override-methods=summary
 115 


 133 COMPANY_ADDRESS := 500 Oracle Parkway, Redwood Shores, CA 94065 USA
 134 
 135 JAVA_PLATFORM := Java Platform
 136 
 137 ifeq ($(IS_DRAFT), true)
 138   DRAFT_MARKER_STR := <br><strong>DRAFT $(VERSION_STRING)</strong>
 139   ifeq ($(VERSION_BUILD), 0)
 140     DRAFT_MARKER_TITLE := [ad-hoc build]
 141   else
 142     DRAFT_MARKER_TITLE := [build $(VERSION_BUILD)]
 143   endif
 144   DRAFT_TEXT := This specification is not final and is subject to change. \
 145       Use is subject to <a href="$(LICENSE_URL)">license terms</a>.
 146 
 147   # Workaround stylesheet bug
 148   HEADER_STYLE := style="margin-top: 9px;"
 149 else
 150   HEADER_STYLE := style="margin-top: 14px;"
 151 endif
 152 
 153 # $1 - Relative prefix to COPYRIGHT_URL
 154 COPYRIGHT_BOTTOM = \
 155     <a href="$(strip $1)$(COPYRIGHT_URL)">Copyright</a> \
 156     &copy; 1993, $(COPYRIGHT_YEAR), $(FULL_COMPANY_NAME), \
 157     $(COMPANY_ADDRESS).<br>All rights reserved. \
 158     Use is subject to <a href="$(LICENSE_URL)">license terms</a> and the \
 159     <a href="$(REDISTRIBUTION_URL)">documentation redistribution policy</a>. \
 160     $(DRAFT_MARKER_STR) <!-- Version $(VERSION_STRING) -->
 161 
 162 JAVADOC_BOTTOM := \
 163     <a href="$(BUG_SUBMIT_URL)">Report a bug or suggest an enhancement</a><br> \
 164     For further API reference and developer documentation see the \
 165     <a href="$(JAVADOC_BASE_URL)" target="_blank">Java SE \
 166     Documentation</a>, which contains more detailed, \
 167     developer-targeted descriptions with conceptual overviews, definitions \
 168     of terms, workarounds, and working code examples.<br> \
 169     Java is a trademark or registered trademark of $(FULL_COMPANY_NAME) in \
 170     the US and other countries.<br> \
 171     $(call COPYRIGHT_BOTTOM, {@docroot}/../)





 172 
 173 JAVADOC_TOP := \
 174     <div style="padding: 6px; text-align: center; font-size: 80%; \
 175     font-family: DejaVu Sans, Arial, Helvetica, sans-serif; \
 176     font-weight: normal;">$(DRAFT_TEXT)</div>
 177 








 178 ################################################################################
 179 # JDK javadoc titles/text snippets
 180 
 181 JDK_SHORT_NAME := Java SE $(VERSION_SPECIFICATION) &amp; JDK $(VERSION_SPECIFICATION)
 182 JDK_LONG_NAME := Java<sup>&reg;</sup> Platform, Standard Edition \
 183     &amp;&nbsp;Java&nbsp;Development&nbsp;Kit
 184 
 185 ################################################################################
 186 # Java SE javadoc titles/text snippets
 187 
 188 JAVASE_SHORT_NAME := Java SE $(VERSION_SPECIFICATION)
 189 JAVASE_LONG_NAME := Java<sup>&reg;</sup> Platform, Standard Edition
 190 
 191 ################################################################################
 192 # Functions
 193 
 194 # Helper function for creating a png file from a dot file generated by the
 195 # GenGraphs tool.
 196 # param 1: SetupJavadocGeneration namespace ($1)
 197 # param 2: module name
 198 #
 199 define setup_gengraph_dot_to_png
 200   $1_$2_DOT_SRC :=  $$($1_GENGRAPHS_DIR)/$2.dot
 201   $1_$2_PNG_TARGET := $$($1_TARGET_DIR)/$2/module-graph.png
 202 
 203     # For each module needing a graph, create a png file from the dot file
 204     # generated by the GenGraphs tool and store it in the target dir.
 205     $$(eval $$(call SetupExecute, gengraphs_png_$1_$2, \
 206         INFO := Running dot for module graphs for $2, \
 207         DEPS := $$(gengraphs_$1_TARGET), \
 208         OUTPUT_FILE := $$($1_$2_PNG_TARGET), \
 209         SUPPORT_DIR := $$($1_GENGRAPHS_DIR), \
 210         COMMAND := $$(DOT) -Tpng -o $$($1_$2_PNG_TARGET) $$($1_$2_DOT_SRC), \
 211     ))
 212 
 213   $1_MODULEGRAPH_TARGETS += $$($1_$2_PNG_TARGET)
 214 endef
 215 
 216 # Helper function to create the overview.html file to use with the -overview
 217 # javadoc option.
 218 # Returns the filename as $1_OVERVIEW.
 219 #
 220 # param 1: SetupJavadocGeneration namespace ($1)
 221 define create_overview_file
 222   $1_OVERVIEW_TEXT := \
 223       <!DOCTYPE html> \
 224       <html><head></head><body> \
 225       #
 226   ifneq ($$($1_GROUPS),)
 227     $1_OVERVIEW_TEXT += \
 228       <p>This document is divided into \
 229       $$(subst 2,two,$$(subst 3,three,$$(words $$($1_GROUPS)))) sections:</p> \
 230       <blockquote><dl> \
 231       #


 259 # Parameter 1 is the name of the rule. This name is used as variable prefix.
 260 # Targets generated are returned as $1_JAVADOC_TARGETS and
 261 # $1_MODULEGRAPH_TARGETS. Note that the index.html file will work as a "touch
 262 # file" for all the magnitude of files that are generated by javadoc.
 263 #
 264 # Remaining parameters are named arguments. These include:
 265 #   MODULES - Modules to generate javadoc for
 266 #   GROUPS - Name of the groups to divide the modules into, if any
 267 #   SHORT_NAME - The short name of this documentation collection
 268 #   LONG_NAME - The long name of this documentation collection
 269 #   TARGET_DIR - Where to store the output
 270 #
 271 SetupApiDocsGeneration = $(NamedParamsMacroTemplate)
 272 define SetupApiDocsGenerationBody
 273 
 274   # Figure out all modules, both specified and transitive indirect exports, that
 275   # will be processed by javadoc.
 276   $1_INDIRECT_EXPORTS := $$(call FindTransitiveIndirectDepsForModules, $$($1_MODULES))
 277   $1_ALL_MODULES := $$(sort $$($1_MODULES) $$($1_INDIRECT_EXPORTS))
 278 
 279   $1_JAVA_ARGS := -Dextlink.spec.version=$$(VERSION_SPECIFICATION) \
 280         -Djspec.version=$$(VERSION_SPECIFICATION)
 281 
 282   ifeq ($$(ENABLE_FULL_DOCS), true)
 283     # Tell the ModuleGraph taglet to generate html links to soon-to-be-created
 284     # png files with module graphs.
 285     $1_JAVA_ARGS += -DenableModuleGraph=true
 286   endif
 287 
 288   # Start with basic options and tags
 289   ifeq ($$($1_OPTIONS), )
 290     $1_OPTIONS := $$(JAVADOC_OPTIONS)
 291   endif
 292   ifeq ($$($1_TAGS), )
 293     $1_TAGS := $$(JAVADOC_TAGS)
 294   endif
 295   $1_OPTIONS += $$($1_TAGS)
 296 
 297   $1_OPTIONS += --module-source-path $$(MODULES_SOURCE_PATH)
 298   $1_OPTIONS += --module $$(call CommaList, $$($1_MODULES))
 299 
 300   # Create a string like "-Xdoclint:all,-syntax,-html,..."


 327   $$(eval $$(call create_overview_file,$1))
 328   $1_OPTIONS += -overview $$($1_OVERVIEW)
 329 
 330   $$(foreach g, $$($1_GROUPS), \
 331     $$(eval $1_OPTIONS += -group "$$($$g_GROUP_NAME)" "$$($$g_GROUP_MODULES)") \
 332   )
 333 
 334   ifeq ($$($1_JAVADOC_CMD), )
 335     $1_JAVADOC_CMD := $$(JAVA) -Djava.awt.headless=true $$($1_JAVA_ARGS) \
 336         $$(NEW_JAVADOC)
 337   else
 338     $1_OPTIONS += $$(addprefix -J, $$($1_JAVA_ARGS))
 339   endif
 340 
 341   $1_VARDEPS := $$($1_JAVA_ARGS) $$($1_OPTIONS) $$(MODULES_SOURCE_PATH) \
 342       $$($1_ALL_MODULES) $$($1_JAVADOC_CMD)
 343   $1_VARDEPS_FILE := $$(call DependOnVariable, $1_VARDEPS, \
 344       $$(SUPPORT_OUTPUTDIR)/docs/$1.vardeps)
 345 
 346   # Get a list of all files in all the source dirs for all included modules
 347   $1_SOURCE_DEPS := $$(call FindFiles, $$(wildcard $$(foreach module, \
 348       $$($1_ALL_MODULES), $$(call FindModuleSrcDirs, $$(module)))))
 349 
 350   $$(eval $$(call SetupExecute, javadoc_$1, \
 351       WARN := Generating $1 javadoc for $$(words $$($1_ALL_MODULES)) modules, \
 352       INFO := Javadoc modules: $$($1_ALL_MODULES), \
 353       DEPS := $$(BUILD_TOOLS_JDK) $$($1_VARDEPS_FILE) $$($1_SOURCE_DEPS) \
 354           $$($1_OVERVIEW), \
 355       OUTPUT_DIR := $$($1_TARGET_DIR), \
 356       SUPPORT_DIR := $$(SUPPORT_OUTPUTDIR)/docs, \
 357       COMMAND := $$($1_JAVADOC_CMD) -d $$($1_TARGET_DIR) $$($1_OPTIONS) \
 358           $$($1_LOG_OPTION), \
 359   ))
 360 
 361   $1_JAVADOC_TARGETS := $$(javadoc_$1_TARGET)
 362 
 363   ifeq ($$(ENABLE_FULL_DOCS), true)
 364     # We have asked ModuleGraph to generate links to png files. Now we must
 365     # produce the png files.
 366 
 367     # Locate which modules has the @moduleGraph tag in their module-info.java
 368     $1_MODULES_NEEDING_GRAPH := $$(strip $$(foreach m, $$($1_ALL_MODULES), \
 369       $$(if $$(shell $$(GREP) -e @moduleGraph \
 370           $$(wildcard $$(addsuffix /module-info.java, \
 371           $$(call FindModuleSrcDirs, $$m)))), \
 372         $$m) \
 373     ))
 374 
 375     # First we run the GenGraph tool. It will query the module structure of the
 376     # running JVM and output .dot files for all existing modules.
 377     GENGRAPHS_PROPS := \
 378         $$(TOPDIR)/make/jdk/src/classes/build/tools/jigsaw/javadoc-graphs.properties
 379 
 380     $1_GENGRAPHS_DIR := $$(SUPPORT_OUTPUTDIR)/docs/$1-gengraphs

 381 
 382     $$(eval $$(call SetupExecute, gengraphs_$1, \
 383         INFO := Running gengraphs for $1 documentation, \
 384         DEPS := $$(BUILD_JIGSAW_TOOLS) $$(GENGRAPHS_PROPS), \
 385         OUTPUT_DIR := $$($1_GENGRAPHS_DIR), \
 386         COMMAND := $$(TOOL_GENGRAPHS) --spec --output $$($1_GENGRAPHS_DIR) \
 387             --dot-attributes $$(GENGRAPHS_PROPS), \
 388     ))
 389 
 390     # For each module needing a graph, create a png file from the dot file
 391     # generated by the GenGraphs tool and store it in the target dir.
 392     # They will depend on gengraphs_$1_TARGET, and will be added to $1.
 393     $$(foreach m, $$($1_MODULES_NEEDING_GRAPH), \
 394       $$(eval $$(call setup_gengraph_dot_to_png,$1,$$m)) \
 395     )
 396   endif
 397 endef
 398 
 399 ################################################################################
 400 # Setup generation of the JDK API documentation (javadoc + modulegraph)
 401 
 402 # Define the groups of the JDK API documentation
 403 JavaSE_GROUP_NAME := Java SE
 404 JavaSE_GROUP_MODULES := $(call ColonList, $(sort java.se \
 405     $(call FindTransitiveIndirectDepsForModules, java.se)))
 406 JavaSE_GROUP_DESCRIPTION := \
 407     The Java Platform, Standard Edition (Java SE) APIs define the core Java \
 408     platform for general-purpose computing. These APIs are in modules whose \
 409     names start with {@code java}. \
 410     #
 411 JDK_GROUPS += JavaSE
 412 


 470 # The reference javadoc is just the same as javase, but using the BootJDK javadoc
 471 # and a stable set of javadoc options.  Typically it is used for generating
 472 # diffs between the reference javadoc and a javadoc bundle of a specific build
 473 # generated in the same way.
 474 
 475 $(eval $(call SetupApiDocsGeneration, REFERENCE_API, \
 476     MODULES := $(JAVASE_MODULES), \
 477     SHORT_NAME := $(JAVASE_SHORT_NAME), \
 478     LONG_NAME := $(JAVASE_LONG_NAME), \
 479     TARGET_DIR := $(IMAGES_OUTPUTDIR)/reference-docs/api, \
 480     JAVADOC_CMD := $(JAVADOC), \
 481     OPTIONS := $(REFERENCE_OPTIONS), \
 482     TAGS := $(REFERENCE_TAGS), \
 483 ))
 484 
 485 # Targets generated are returned in REFERENCE_API_JAVADOC_TARGETS and
 486 # REFERENCE_API_MODULEGRAPH_TARGETS.
 487 
 488 ################################################################################
 489 
 490 # Copy the global resources, including the top-level redirect index.html







 491 GLOBAL_SPECS_RESOURCES_DIR := $(TOPDIR)/make/data/docs-resources/
 492 $(eval $(call SetupCopyFiles, COPY_GLOBAL_RESOURCES, \
 493     SRC := $(GLOBAL_SPECS_RESOURCES_DIR), \
 494     FILES := $(call FindFiles, $(GLOBAL_SPECS_RESOURCES_DIR)), \
 495     DEST := $(DOCS_OUTPUTDIR), \
 496 ))
 497 JDK_INDEX_TARGETS += $(COPY_GLOBAL_RESOURCES)
 498 
 499 # Copy the legal notices distributed with the docs bundle
 500 $(eval $(call SetupCopyFiles, COPY_DOCS_LEGAL_NOTICES, \
 501     SRC := $(TOPDIR)/src/jdk.javadoc/share/legal, \
 502     FILES := $(wildcard $(TOPDIR)/src/jdk.javadoc/share/legal/*), \
 503     DEST := $(DOCS_OUTPUTDIR)/legal, \
 504 ))
 505 JDK_INDEX_TARGETS += $(COPY_DOCS_LEGAL_NOTICES)
 506 
 507 ################################################################################
 508 # Copy JDK specs files
 509 
 510 # For all non html/md files in $module/share/specs directories, copy them
 511 # unmodified
 512 
 513 ALL_MODULES := $(call FindAllModules)
 514 COPY_SPEC_FILTER := %.gif %.jpg %.mib %.css
 515 
 516 $(foreach m, $(ALL_MODULES), \
 517   $(eval SPECS_$m := $(call FindModuleSpecsDirs, $m)) \
 518   $(foreach d, $(SPECS_$m), \
 519     $(if $(filter $(COPY_SPEC_FILTER), $(call FindFiles, $d)), \
 520       $(eval $(call SetupCopyFiles, COPY_$m, \
 521           SRC := $d, \
 522           FILES := $(filter $(COPY_SPEC_FILTER), $(call FindFiles, $d)), \
 523           DEST := $(DOCS_OUTPUTDIR)/specs/, \
 524       )) \
 525       $(eval JDK_SPECS_TARGETS += $(COPY_$m)) \
 526     ) \
 527   ) \
 528 )
 529 
 530 # Create copyright footer files that can be provided as input to pandoc. We
 531 # need different files for different relative paths to the copyright.html
 532 # file. The number 0-2 below represent how many extra directory levels down
 533 # below the specs dir the specs html file is located. Each file name is
 534 # stored in a variable SPECS_BOTTOM_FILE_$n where $n is 0, 1 or 2.
 535 SPECS_BOTTOM = <hr/>$(COPYRIGHT_BOTTOM)
 536 # The legal dir is one ../ below the specs dir, so start with one ../.
 537 specs_bottom_rel_path := ../
 538 $(foreach n, 0 1 2, \
 539   $(eval SPECS_BOTTOM_FILE_$n := $(SUPPORT_OUTPUTDIR)/docs/full-specs-bottom-$n.txt) \
 540   $(eval SPECS_BOTTOM_$n := $(call SPECS_BOTTOM,$(specs_bottom_rel_path))) \
 541   $(eval $(SPECS_BOTTOM_FILE_$n): \
 542       $(call DependOnVariable, SPECS_BOTTOM_$n) ; \
 543       $(PRINTF) '$(SPECS_BOTTOM_$n)' > $$@ \
 544   ) \
 545   $(eval specs_bottom_rel_path := $(specs_bottom_rel_path)../) \
 546 )
 547 
 548 # For all html files in $module/share/specs directories, copy and add the
 549 # copyright footer.
 550 
 551 $(foreach m, $(ALL_MODULES), \
 552   $(eval SPECS_$m := $(call FindModuleSpecsDirs, $m)) \
 553   $(foreach d, $(SPECS_$m), \
 554     $(foreach f, $(filter %.html, $(call FindFiles, $d)), \
 555       $(eval $m_$f_NOF_SUBDIRS := $(words $(subst /, $(SPACE), $(subst $d, , $(dir $f))))) \
 556       $(eval $m_$f_NAME := PROCESS_HTML_$m_$(strip $(call RelativePath, $f, $(TOPDIR)))) \
 557       $(eval $(call SetupTextFileProcessing, $($m_$f_NAME), \
 558           SOURCE_FILES := $f, \
 559           SOURCE_BASE_DIR := $d, \
 560           OUTPUT_DIR := $(DOCS_OUTPUTDIR)/specs/, \
 561           REPLACEMENTS := \
 562               </body> => $(SPECS_BOTTOM_$($m_$f_NOF_SUBDIRS))</body>, \
 563       )) \
 564       $(eval JDK_SPECS_TARGETS += $($($m_$f_NAME))) \
 565     ) \
 566   ) \
 567 )
 568 
 569 ifeq ($(ENABLE_PANDOC), true)
 570   # For all markdown files in $module/share/specs directories, convert them to
 571   # html, if we have pandoc (otherwise we'll just skip this).
 572 
 573   GLOBAL_SPECS_DEFAULT_CSS_FILE := $(DOCS_OUTPUTDIR)/resources/jdk-default.css
 574 
 575   $(foreach m, $(ALL_MODULES), \
 576     $(eval SPECS_$m := $(call FindModuleSpecsDirs, $m)) \
 577     $(foreach d, $(SPECS_$m), \
 578       $(foreach f, $(filter %.md, $(call FindFiles, $d)), \
 579         $(eval $m_$f_NOF_SUBDIRS := $(words $(subst /, $(SPACE), $(subst $d, , $(dir $f))))) \
 580         $(eval $m_$f_BOTTOM_FILE := $(SPECS_BOTTOM_FILE_$($m_$f_NOF_SUBDIRS))) \
 581         $(eval $m_$f_NAME := SPECS_TO_HTML_$m_$(strip $(call RelativePath, $f, $(TOPDIR)))) \
 582         $(eval $(call SetupProcessMarkdown, $($m_$f_NAME), \
 583             SRC := $d, \
 584             FILES := $f, \
 585             DEST := $(DOCS_OUTPUTDIR)/specs/, \
 586             CSS := $(GLOBAL_SPECS_DEFAULT_CSS_FILE), \
 587             OPTIONS := -A $($m_$f_BOTTOM_FILE), \
 588             EXTRA_DEPS := $($m_$f_BOTTOM_FILE), \
 589             POST_PROCESS := $(TOOL_FIXUPPANDOC), \
 590         )) \
 591         $(eval JDK_SPECS_TARGETS += $($($m_$f_NAME))) \
 592       ) \
 593     ) \
 594   )
 595 
 596   # For all markdown files in $module/share/man directories, convert them to
 597   # html.
 598 
 599   # Create dynamic man pages from markdown using pandoc. We need
 600   # PANDOC_HTML_MANPAGE_FILTER, a wrapper around
 601   # PANDOC_HTML_MANPAGE_FILTER_JAVASCRIPT. This is created by buildtools-jdk.
 602 
 603   # We should also depend on the source javascript filter
 604   PANDOC_HTML_MANPAGE_FILTER_JAVASCRIPT := \
 605       $(TOPDIR)/make/scripts/pandoc-html-manpage-filter.js
 606 
 607   $(foreach m, $(ALL_MODULES), \
 608     $(eval MAN_$m := $(call FindModuleManDirs, $m)) \
 609     $(foreach d, $(MAN_$m), \
 610       $(foreach f, $(filter %.md, $(call FindFiles, $d)), \
 611         $(eval $m_$f_NAME := MAN_TO_HTML_$m_$(strip $(call RelativePath, $f, $(TOPDIR)))) \
 612         $(eval $(call SetupProcessMarkdown, $($m_$f_NAME), \
 613             SRC := $d, \
 614             FILES := $f, \
 615             DEST := $(DOCS_OUTPUTDIR)/specs/man, \
 616             FILTER := $(PANDOC_HTML_MANPAGE_FILTER), \
 617             CSS := $(GLOBAL_SPECS_DEFAULT_CSS_FILE), \
 618             REPLACEMENTS := @@VERSION_SHORT@@ => $(VERSION_SHORT), \
 619             OPTIONS := -A $(SPECS_BOTTOM_FILE_1), \
 620             POST_PROCESS := $(TOOL_FIXUPPANDOC), \
 621             EXTRA_DEPS := $(PANDOC_HTML_MANPAGE_FILTER) \
 622                 $(PANDOC_HTML_MANPAGE_FILTER_JAVASCRIPT) \
 623                 $(SPECS_BOTTOM_FILE_1), \
 624         )) \
 625         $(eval JDK_SPECS_TARGETS += $($($m_$f_NAME))) \
 626       ) \
 627     ) \
 628   )
 629 
 630   # The html generated from markdown also needs the css file
 631   JDK_SPECS_TARGETS += $(COPY_GLOBAL_RESOURCES)
 632 endif
 633 
 634 # Special treatment for generated documentation
 635 
 636 JDWP_PROTOCOL := $(SUPPORT_OUTPUTDIR)/gensrc/jdk.jdi/jdwp-protocol.html
 637 $(eval $(call SetupTextFileProcessing, PROCESS_JDWP_PROTOCOL, \
 638     SOURCE_FILES := $(JDWP_PROTOCOL), \
 639     OUTPUT_DIR := $(DOCS_OUTPUTDIR)/specs/jdwp, \
 640     REPLACEMENTS := \
 641         </body> => $(SPECS_BOTTOM_1)</body>, \
 642 ))
 643 JDK_SPECS_TARGETS += $(PROCESS_JDWP_PROTOCOL)
 644 
 645 # Get jvmti.html from the main jvm variant (all variants' jvmti.html are identical).
 646 JVMTI_HTML ?= $(HOTSPOT_OUTPUTDIR)/variant-$(JVM_VARIANT_MAIN)/gensrc/jvmtifiles/jvmti.html
 647 $(eval $(call SetupTextFileProcessing, PROCESS_JVMTI_HTML, \
 648     SOURCE_FILES := $(JVMTI_HTML), \
 649     OUTPUT_DIR := $(DOCS_OUTPUTDIR)/specs/, \
 650     REPLACEMENTS := \
 651         </body> => $(SPECS_BOTTOM_0)</body>, \
 652 ))
 653 JDK_SPECS_TARGETS += $(PROCESS_JVMTI_HTML)
 654 
 655 ################################################################################
 656 # Optional target which bundles all generated javadocs into a zip archive.
 657 
 658 JAVADOC_ZIP_NAME := jdk-$(VERSION_STRING)-docs.zip
 659 JAVADOC_ZIP_FILE := $(OUTPUTDIR)/bundles/$(JAVADOC_ZIP_NAME)
 660 
 661 $(eval $(call SetupZipArchive, BUILD_JAVADOC_ZIP, \
 662     SRC := $(DOCS_OUTPUTDIR), \
 663     ZIP := $(JAVADOC_ZIP_FILE), \
 664     EXTRA_DEPS := $(JDK_API_JAVADOC_TARGETS) $(JDK_API_MODULEGRAPH_TARGETS) \
 665         $(JDK_SPECS_TARGETS), \
 666 ))
 667 
 668 ZIP_TARGETS += $(BUILD_JAVADOC_ZIP)
 669 
 670 ################################################################################
 671 # Hook to include the corresponding custom file, if present.
 672 $(eval $(call IncludeCustomExtension, Docs-post.gmk))
 673 
 674 ################################################################################
 675 
 676 docs-jdk-api-javadoc: $(JDK_API_JAVADOC_TARGETS) $(JDK_API_CUSTOM_TARGETS)
 677 
 678 docs-jdk-api-modulegraph: $(JDK_API_MODULEGRAPH_TARGETS)
 679 
 680 docs-javase-api-javadoc: $(JAVASE_API_JAVADOC_TARGETS) $(JAVASE_API_CUSTOM_TARGETS)
 681 
 682 docs-javase-api-modulegraph: $(JAVASE_API_MODULEGRAPH_TARGETS)
 683 
 684 docs-reference-api-javadoc: $(REFERENCE_API_JAVADOC_TARGETS) $(REFERENCE_API_CUSTOM_TARGETS)
 685 
 686 docs-reference-api-modulegraph: $(REFERENCE_API_MODULEGRAPH_TARGETS)
 687 
 688 docs-jdk-specs: $(JDK_SPECS_TARGETS)
 689 
 690 docs-jdk-index: $(JDK_INDEX_TARGETS)
 691 
 692 docs-zip: $(ZIP_TARGETS)
   1 # Copyright (c) 1997, 2018, 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 ProcessMarkdown.gmk

  31 include ZipArchive.gmk
  32 include $(TOPDIR)/make/ToolsJdk.gmk
  33 include $(TOPDIR)/make/ModuleTools.gmk
  34 
  35 # This is needed to properly setup DOCS_MODULES.
  36 $(eval $(call ReadImportMetaData))
  37 
  38 ################################################################################
  39 # Hook to include the corresponding custom file, if present.
  40 $(eval $(call IncludeCustomExtension, Docs.gmk))
  41 
  42 ################################################################################
  43 # This file generates all documentation for OpenJDK.
  44 #
  45 # We will generate API documentation for two different selections of the source
  46 # code: "Java SE", which contains just the modules covered by the top-level
  47 # module java.se and "JDK", which covers all of Java SE and also all
  48 # other available modules that should be documented, including imported modules,
  49 # if any.
  50 #
  51 # We will also generate separate, free-standing specifications from either
  52 # markdown or existing html files.
  53 #
  54 
  55 ################################################################################
  56 # Javadoc settings
  57 
  58 # On top of the sources that was used to compile the JDK, we need some
  59 # extra java.rmi sources that are used just for javadoc.
  60 MODULES_SOURCE_PATH := $(call PathList, $(call GetModuleSrcPath) \
  61     $(SUPPORT_OUTPUTDIR)/rmic/* $(TOPDIR)/src/*/share/doc/stub)
  62 
  63 # URLs
  64 JAVADOC_BASE_URL := https://docs.oracle.com/pls/topic/lookup?ctx=javase$(VERSION_NUMBER)&amp;id=homepage
  65 BUG_SUBMIT_URL := https://bugreport.java.com/bugreport/
  66 COPYRIGHT_URL := {@docroot}/../legal/copyright.html
  67 LICENSE_URL := https://www.oracle.com/technetwork/java/javase/terms/license/java$(VERSION_NUMBER)speclicense.html
  68 REDISTRIBUTION_URL := https://www.oracle.com/technetwork/java/redist-137594.html
  69 
  70 # In order to get a specific ordering it's necessary to specify the total
  71 # ordering of tags as the tags are otherwise ordered in order of definition.
  72 JAVADOC_TAGS := \
  73     -tag beaninfo:X \
  74     -tag revised:X \
  75     -tag since.unbundled:X \
  76     -tag spec:X \
  77     -tag specdefault:X \
  78     -tag Note:X \
  79     -tag ToDo:X \
  80     -tag 'apiNote:a:API Note:' \
  81     -tag 'implSpec:a:Implementation Requirements:' \
  82     -tag 'implNote:a:Implementation Note:' \
  83     -tag param \
  84     -tag return \
  85     -tag throws \


  86     -taglet build.tools.taglet.ModuleGraph \

  87     -tag since \
  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.ExtLink \
  94     -taglet build.tools.taglet.Incubating \
  95     -tagletpath $(BUILDTOOLS_OUTPUTDIR)/jdk_tools_classes \
  96     $(CUSTOM_JAVADOC_TAGS) \
  97     #
  98 
  99 # The reference tags must stay stable to allow for comparisons across the
 100 # development cycle. If JAVADOC_TAGS needs to change, make sure that
 101 # REFERENCE_TAGS remains unchanged, by copying and hardcoding, if necessary.
 102 REFERENCE_TAGS := $(JAVADOC_TAGS)
 103 
 104 # Which doclint checks to ignore
 105 JAVADOC_DISABLED_DOCLINT := accessibility html missing syntax reference
 106 
 107 # The initial set of options for javadoc
 108 JAVADOC_OPTIONS := -use -keywords -notimestamp \
 109     -serialwarn -encoding ISO-8859-1 -docencoding UTF-8 -breakiterator \
 110     -splitIndex --system none -javafx --expand-requires transitive \
 111     --override-methods=summary
 112 


 130 COMPANY_ADDRESS := 500 Oracle Parkway, Redwood Shores, CA 94065 USA
 131 
 132 JAVA_PLATFORM := Java Platform
 133 
 134 ifeq ($(IS_DRAFT), true)
 135   DRAFT_MARKER_STR := <br><strong>DRAFT $(VERSION_STRING)</strong>
 136   ifeq ($(VERSION_BUILD), 0)
 137     DRAFT_MARKER_TITLE := [ad-hoc build]
 138   else
 139     DRAFT_MARKER_TITLE := [build $(VERSION_BUILD)]
 140   endif
 141   DRAFT_TEXT := This specification is not final and is subject to change. \
 142       Use is subject to <a href="$(LICENSE_URL)">license terms</a>.
 143 
 144   # Workaround stylesheet bug
 145   HEADER_STYLE := style="margin-top: 9px;"
 146 else
 147   HEADER_STYLE := style="margin-top: 14px;"
 148 endif
 149 









 150 JAVADOC_BOTTOM := \
 151     <a href="$(BUG_SUBMIT_URL)">Report a bug or suggest an enhancement</a><br> \
 152     For further API reference and developer documentation see the \
 153     <a href="$(JAVADOC_BASE_URL)" target="_blank">Java SE \
 154     Documentation</a>, which contains more detailed, \
 155     developer-targeted descriptions with conceptual overviews, definitions \
 156     of terms, workarounds, and working code examples.<br> \
 157     Java is a trademark or registered trademark of $(FULL_COMPANY_NAME) in \
 158     the US and other countries.<br> \
 159     <a href="$(COPYRIGHT_URL)">Copyright</a> \
 160     &copy; 1993, $(COPYRIGHT_YEAR), $(FULL_COMPANY_NAME), \
 161     $(COMPANY_ADDRESS).<br>All rights reserved. \
 162     Use is subject to <a href="$(LICENSE_URL)">license terms</a> and the \
 163     <a href="$(REDISTRIBUTION_URL)">documentation redistribution policy</a>. \
 164     $(DRAFT_MARKER_STR) <!-- Version $(VERSION_STRING) -->
 165 
 166 JAVADOC_TOP := \
 167     <div style="padding: 6px; text-align: center; font-size: 80%; \
 168     font-family: DejaVu Sans, Arial, Helvetica, sans-serif; \
 169     font-weight: normal;">$(DRAFT_TEXT)</div>
 170 
 171 JDK_INDEX_CONTENT := \
 172     <!DOCTYPE html> \
 173     <html lang="en"> \
 174     <head> \
 175     <meta http-equiv="refresh" content="0;url=api/index.html"> \
 176     </head> \
 177     </html>
 178 
 179 ################################################################################
 180 # JDK javadoc titles/text snippets
 181 
 182 JDK_SHORT_NAME := Java SE $(VERSION_SPECIFICATION) &amp; JDK $(VERSION_SPECIFICATION)
 183 JDK_LONG_NAME := Java<sup>&reg;</sup> Platform, Standard Edition \
 184     &amp;&nbsp;Java&nbsp;Development&nbsp;Kit
 185 
 186 ################################################################################
 187 # Java SE javadoc titles/text snippets
 188 
 189 JAVASE_SHORT_NAME := Java SE $(VERSION_SPECIFICATION)
 190 JAVASE_LONG_NAME := Java<sup>&reg;</sup> Platform, Standard Edition
 191 
 192 ################################################################################
 193 # Functions
 194 
 195 # Helper function for creating a png file from a dot file generated by the
 196 # GenGraphs tool.
 197 # param 1: SetupJavadocGeneration namespace ($1)
 198 # param 2: module name
 199 #
 200 define setup_gengraph_dot_to_png
 201   $1_$2_DOT_SRC :=  $$($1_GENGRAPHS_DIR)/$2.dot
 202   $1_$2_PNG_TARGET := $$($1_TARGET_DIR)/$2/module-graph.png
 203 
 204     # For each module needing a graph, create a png file from the dot file
 205     # generated by the GenGraphs tool and store it in the target dir.
 206     $$($1_$2_PNG_TARGET): $$($1_GENGRAPHS_MARKER)
 207         $$(call MakeDir, $$(@D))
 208         $$(call ExecuteWithLog, $$($1_$2_DOT_SRC), \
 209             $$(DOT) -Tpng -o $$($1_$2_PNG_TARGET) $$($1_$2_DOT_SRC))



 210 
 211   $1_MODULEGRAPH_TARGETS += $$($1_$2_PNG_TARGET)
 212 endef
 213 
 214 # Helper function to create the overview.html file to use with the -overview
 215 # javadoc option.
 216 # Returns the filename as $1_OVERVIEW.
 217 #
 218 # param 1: SetupJavadocGeneration namespace ($1)
 219 define create_overview_file
 220   $1_OVERVIEW_TEXT := \
 221       <!DOCTYPE html> \
 222       <html><head></head><body> \
 223       #
 224   ifneq ($$($1_GROUPS),)
 225     $1_OVERVIEW_TEXT += \
 226       <p>This document is divided into \
 227       $$(subst 2,two,$$(subst 3,three,$$(words $$($1_GROUPS)))) sections:</p> \
 228       <blockquote><dl> \
 229       #


 257 # Parameter 1 is the name of the rule. This name is used as variable prefix.
 258 # Targets generated are returned as $1_JAVADOC_TARGETS and
 259 # $1_MODULEGRAPH_TARGETS. Note that the index.html file will work as a "touch
 260 # file" for all the magnitude of files that are generated by javadoc.
 261 #
 262 # Remaining parameters are named arguments. These include:
 263 #   MODULES - Modules to generate javadoc for
 264 #   GROUPS - Name of the groups to divide the modules into, if any
 265 #   SHORT_NAME - The short name of this documentation collection
 266 #   LONG_NAME - The long name of this documentation collection
 267 #   TARGET_DIR - Where to store the output
 268 #
 269 SetupApiDocsGeneration = $(NamedParamsMacroTemplate)
 270 define SetupApiDocsGenerationBody
 271 
 272   # Figure out all modules, both specified and transitive indirect exports, that
 273   # will be processed by javadoc.
 274   $1_INDIRECT_EXPORTS := $$(call FindTransitiveIndirectDepsForModules, $$($1_MODULES))
 275   $1_ALL_MODULES := $$(sort $$($1_MODULES) $$($1_INDIRECT_EXPORTS))
 276 
 277   $1_JAVA_ARGS := -Dextlink.spec.version=$$(VERSION_SPECIFICATION)

 278 
 279   ifeq ($$(ENABLE_FULL_DOCS), true)
 280     # Tell the ModuleGraph taglet to generate html links to soon-to-be-created
 281     # png files with module graphs.
 282     $1_JAVA_ARGS += -DenableModuleGraph=true
 283   endif
 284 
 285   # Start with basic options and tags
 286   ifeq ($$($1_OPTIONS), )
 287     $1_OPTIONS := $$(JAVADOC_OPTIONS)
 288   endif
 289   ifeq ($$($1_TAGS), )
 290     $1_TAGS := $$(JAVADOC_TAGS)
 291   endif
 292   $1_OPTIONS += $$($1_TAGS)
 293 
 294   $1_OPTIONS += --module-source-path $$(MODULES_SOURCE_PATH)
 295   $1_OPTIONS += --module $$(call CommaList, $$($1_MODULES))
 296 
 297   # Create a string like "-Xdoclint:all,-syntax,-html,..."


 324   $$(eval $$(call create_overview_file,$1))
 325   $1_OPTIONS += -overview $$($1_OVERVIEW)
 326 
 327   $$(foreach g, $$($1_GROUPS), \
 328     $$(eval $1_OPTIONS += -group "$$($$g_GROUP_NAME)" "$$($$g_GROUP_MODULES)") \
 329   )
 330 
 331   ifeq ($$($1_JAVADOC_CMD), )
 332     $1_JAVADOC_CMD := $$(JAVA) -Djava.awt.headless=true $$($1_JAVA_ARGS) \
 333         $$(NEW_JAVADOC)
 334   else
 335     $1_OPTIONS += $$(addprefix -J, $$($1_JAVA_ARGS))
 336   endif
 337 
 338   $1_VARDEPS := $$($1_JAVA_ARGS) $$($1_OPTIONS) $$(MODULES_SOURCE_PATH) \
 339       $$($1_ALL_MODULES) $$($1_JAVADOC_CMD)
 340   $1_VARDEPS_FILE := $$(call DependOnVariable, $1_VARDEPS, \
 341       $$(SUPPORT_OUTPUTDIR)/docs/$1.vardeps)
 342 
 343   # Get a list of all files in all the source dirs for all included modules
 344   $1_SOURCE_DEPS := $$(call CacheFind, $$(wildcard $$(foreach module, \
 345       $$($1_ALL_MODULES), $$(call FindModuleSrcDirs, $$(module)))))
 346 
 347   # Javadoc creates a lot of files but use index.html as a marker
 348   $$($1_TARGET_DIR)/index.html: $$(BUILD_TOOLS_JDK) $$($1_VARDEPS_FILE) \
 349       $$($1_SOURCE_DEPS) $$($1_OVERVIEW)
 350         $$(call LogWarn, Generating $1 javadoc for \
 351             $$(words $$($1_ALL_MODULES)) modules)
 352         $$(call LogInfo, Javadoc modules: $$($1_ALL_MODULES))
 353         $$(call MakeDir, $$($1_TARGET_DIR))
 354         $$(call ExecuteWithLog, $$(SUPPORT_OUTPUTDIR)/docs/$1, \
 355             $$($1_JAVADOC_CMD) -d $$($1_TARGET_DIR) \
 356                 $$($1_OPTIONS) $$($1_LOG_OPTION))
 357 
 358   $1_JAVADOC_TARGETS := $$($1_TARGET_DIR)/index.html
 359 
 360   ifeq ($$(ENABLE_FULL_DOCS), true)
 361     # We have asked ModuleGraph to generate links to png files. Now we must
 362     # produce the png files.
 363 
 364     # Locate which modules has the @moduleGraph tag in their module-info.java
 365     $1_MODULES_NEEDING_GRAPH := $$(strip $$(foreach m, $$($1_ALL_MODULES), \
 366       $$(if $$(shell $$(GREP) -e @moduleGraph \
 367           $$(wildcard $$(addsuffix /module-info.java, \
 368           $$(call FindModuleSrcDirs, $$m)))), \
 369         $$m) \
 370     ))
 371 
 372     # First we run the GenGraph tool. It will query the module structure of the
 373     # running JVM and output .dot files for all existing modules.
 374     GENGRAPHS_PROPS := \
 375         $$(TOPDIR)/make/jdk/src/classes/build/tools/jigsaw/javadoc-graphs.properties
 376 
 377     $1_GENGRAPHS_DIR := $$(SUPPORT_OUTPUTDIR)/docs/$1-gengraphs
 378     $1_GENGRAPHS_MARKER := $$($1_GENGRAPHS_DIR)/_gengraphs_run.marker
 379 
 380     $$($1_GENGRAPHS_MARKER): $$(BUILD_JIGSAW_TOOLS) $$(GENGRAPHS_PROPS)
 381         $$(call LogInfo, Running gengraphs for $1 documentation)
 382         $$(call MakeDir, $$($1_GENGRAPHS_DIR))
 383         $$(call ExecuteWithLog, $$($1_GENGRAPHS_DIR)/gengraphs, \
 384             $$(TOOL_GENGRAPHS) --spec --output $$($1_GENGRAPHS_DIR) \
 385             --dot-attributes $$(GENGRAPHS_PROPS) && \
 386             $$(TOUCH) $$($1_GENGRAPHS_MARKER))
 387 
 388     # For each module needing a graph, create a png file from the dot file
 389     # generated by the GenGraphs tool and store it in the target dir.
 390     # They will depend on $1_GENGRAPHS_MARKER, and will be added to $1.
 391     $$(foreach m, $$($1_MODULES_NEEDING_GRAPH), \
 392       $$(eval $$(call setup_gengraph_dot_to_png,$1,$$m)) \
 393     )
 394   endif
 395 endef
 396 
 397 ################################################################################
 398 # Setup generation of the JDK API documentation (javadoc + modulegraph)
 399 
 400 # Define the groups of the JDK API documentation
 401 JavaSE_GROUP_NAME := Java SE
 402 JavaSE_GROUP_MODULES := $(call ColonList, $(sort java.se \
 403     $(call FindTransitiveIndirectDepsForModules, java.se)))
 404 JavaSE_GROUP_DESCRIPTION := \
 405     The Java Platform, Standard Edition (Java SE) APIs define the core Java \
 406     platform for general-purpose computing. These APIs are in modules whose \
 407     names start with {@code java}. \
 408     #
 409 JDK_GROUPS += JavaSE
 410 


 468 # The reference javadoc is just the same as javase, but using the BootJDK javadoc
 469 # and a stable set of javadoc options.  Typically it is used for generating
 470 # diffs between the reference javadoc and a javadoc bundle of a specific build
 471 # generated in the same way.
 472 
 473 $(eval $(call SetupApiDocsGeneration, REFERENCE_API, \
 474     MODULES := $(JAVASE_MODULES), \
 475     SHORT_NAME := $(JAVASE_SHORT_NAME), \
 476     LONG_NAME := $(JAVASE_LONG_NAME), \
 477     TARGET_DIR := $(IMAGES_OUTPUTDIR)/reference-docs/api, \
 478     JAVADOC_CMD := $(JAVADOC), \
 479     OPTIONS := $(REFERENCE_OPTIONS), \
 480     TAGS := $(REFERENCE_TAGS), \
 481 ))
 482 
 483 # Targets generated are returned in REFERENCE_API_JAVADOC_TARGETS and
 484 # REFERENCE_API_MODULEGRAPH_TARGETS.
 485 
 486 ################################################################################
 487 
 488 JDK_INDEX_HTML := $(DOCS_OUTPUTDIR)/index.html
 489 
 490 $(JDK_INDEX_HTML):
 491         $(ECHO) '$(JDK_INDEX_CONTENT)' > $@
 492 
 493 JDK_INDEX_TARGETS += $(JDK_INDEX_HTML)
 494 
 495 # Copy the global resources
 496 GLOBAL_SPECS_RESOURCES_DIR := $(TOPDIR)/make/data/docs-resources/
 497 $(eval $(call SetupCopyFiles, COPY_GLOBAL_RESOURCES, \
 498     SRC := $(GLOBAL_SPECS_RESOURCES_DIR), \
 499     FILES := $(call CacheFind, $(GLOBAL_SPECS_RESOURCES_DIR)), \
 500     DEST := $(DOCS_OUTPUTDIR), \
 501 ))
 502 JDK_INDEX_TARGETS += $(COPY_GLOBAL_RESOURCES)
 503 
 504 # Copy the legal notices distributed with the docs bundle
 505 $(eval $(call SetupCopyFiles, COPY_DOCS_LEGAL_NOTICES, \
 506     SRC := $(TOPDIR)/src/jdk.javadoc/share/legal, \
 507     FILES := $(wildcard $(TOPDIR)/src/jdk.javadoc/share/legal/*), \
 508     DEST := $(DOCS_OUTPUTDIR)/legal, \
 509 ))
 510 JDK_INDEX_TARGETS += $(COPY_DOCS_LEGAL_NOTICES)
 511 
 512 ################################################################################
 513 # Copy JDK specs files
 514 
 515 # For all html documentation in $module/share/specs directories, copy it
 516 # unmodified
 517 
 518 ALL_MODULES := $(call FindAllModules)
 519 COPY_SPEC_FILTER := %.html %.gif %.jpg %.mib %.css
 520 
 521 $(foreach m, $(ALL_MODULES), \
 522   $(eval SPECS_$m := $(call FindModuleSpecsDirs, $m)) \
 523   $(foreach d, $(SPECS_$m), \
 524     $(if $(filter $(COPY_SPEC_FILTER), $(call CacheFind, $d)), \
 525       $(eval $(call SetupCopyFiles, COPY_$m, \
 526           SRC := $d, \
 527           FILES := $(filter $(COPY_SPEC_FILTER), $(call CacheFind, $d)), \
 528           DEST := $(DOCS_OUTPUTDIR)/specs/, \
 529       )) \
 530       $(eval JDK_SPECS_TARGETS += $(COPY_$m)) \
 531     ) \
 532   ) \
 533 )
 534 
 535 ifeq ($(ENABLE_FULL_DOCS), true)







































 536   # For all markdown files in $module/share/specs directories, convert them to
 537   # html.
 538 
 539   GLOBAL_SPECS_DEFAULT_CSS_FILE := $(DOCS_OUTPUTDIR)/resources/jdk-default.css
 540 
 541   $(foreach m, $(ALL_MODULES), \
 542     $(eval SPECS_$m := $(call FindModuleSpecsDirs, $m)) \
 543     $(foreach d, $(SPECS_$m), \
 544       $(if $(filter %.md, $(call CacheFind, $d)), \
 545         $(eval $m_$d_NAME := SPECS_TO_HTML_$m_$(strip $(call RelativePath, $d, $(TOPDIR)))) \
 546         $(eval $(call SetupProcessMarkdown, $($m_$d_NAME), \


 547             SRC := $d, \
 548             FILES := $(filter %.md, $(call CacheFind, $d)), \
 549             DEST := $(DOCS_OUTPUTDIR)/specs/, \
 550             CSS := $(GLOBAL_SPECS_DEFAULT_CSS_FILE), \



 551         )) \
 552         $(eval JDK_SPECS_TARGETS += $($($m_$d_NAME))) \
 553       ) \
 554     ) \
 555   )
 556 
 557   # For all markdown files in $module/share/man directories, convert them to
 558   # html.









 559   $(foreach m, $(ALL_MODULES), \
 560     $(eval MAN_$m := $(call FindModuleManDirs, $m)) \
 561     $(foreach d, $(MAN_$m), \
 562       $(if $(filter %.md, $(call CacheFind, $d)), \
 563         $(eval $m_$d_NAME := MAN_TO_HTML_$m_$(strip $(call RelativePath, $d, $(TOPDIR)))) \
 564         $(eval $(call SetupProcessMarkdown, $($m_$d_NAME), \
 565             SRC := $d, \
 566             FILES := $(filter %.md, $(call CacheFind, $d)), \
 567             DEST := $(DOCS_OUTPUTDIR)/specs/man, \

 568             CSS := $(GLOBAL_SPECS_DEFAULT_CSS_FILE), \
 569             REPLACEMENTS := @@VERSION_SHORT@@ => $(VERSION_SHORT), \





 570         )) \
 571         $(eval JDK_SPECS_TARGETS += $($($m_$d_NAME))) \
 572       ) \
 573     ) \
 574   )
 575 
 576   # The html generated from markdown also needs the css file
 577   JDK_SPECS_TARGETS += $(COPY_GLOBAL_RESOURCES)
 578 endif
 579 
 580 # Special treatment for generated documentation
 581 
 582 JDWP_PROTOCOL := $(SUPPORT_OUTPUTDIR)/gensrc/jdk.jdi/jdwp-protocol.html
 583 $(eval $(call SetupCopyFiles, COPY_JDWP_PROTOCOL, \
 584     FILES := $(JDWP_PROTOCOL), \
 585     DEST := $(DOCS_OUTPUTDIR)/specs/jdwp, \


 586 ))
 587 JDK_SPECS_TARGETS += $(COPY_JDWP_PROTOCOL)
 588 
 589 # Get jvmti.html from the main jvm variant (all variants' jvmti.html are identical).
 590 JVMTI_HTML ?= $(HOTSPOT_OUTPUTDIR)/variant-$(JVM_VARIANT_MAIN)/gensrc/jvmtifiles/jvmti.html
 591 $(eval $(call SetupCopyFiles, COPY_JVMTI_HTML, \
 592     FILES := $(JVMTI_HTML), \
 593     DEST := $(DOCS_OUTPUTDIR)/specs, \


 594 ))
 595 JDK_SPECS_TARGETS += $(COPY_JVMTI_HTML)
 596 
 597 ################################################################################
 598 # Optional target which bundles all generated javadocs into a zip archive.
 599 
 600 JAVADOC_ZIP_NAME := jdk-$(VERSION_STRING)-docs.zip
 601 JAVADOC_ZIP_FILE := $(OUTPUTDIR)/bundles/$(JAVADOC_ZIP_NAME)
 602 
 603 $(eval $(call SetupZipArchive, BUILD_JAVADOC_ZIP, \
 604     SRC := $(DOCS_OUTPUTDIR), \
 605     ZIP := $(JAVADOC_ZIP_FILE), \
 606     EXTRA_DEPS := $(JDK_API_JAVADOC_TARGETS) $(JDK_API_MODULEGRAPH_TARGETS) \
 607         $(JDK_SPECS_TARGETS), \
 608 ))
 609 
 610 ZIP_TARGETS += $(BUILD_JAVADOC_ZIP)




 611 
 612 ################################################################################
 613 
 614 docs-jdk-api-javadoc: $(JDK_API_JAVADOC_TARGETS) $(JDK_API_CUSTOM_TARGETS)
 615 
 616 docs-jdk-api-modulegraph: $(JDK_API_MODULEGRAPH_TARGETS)
 617 
 618 docs-javase-api-javadoc: $(JAVASE_API_JAVADOC_TARGETS) $(JAVASE_API_CUSTOM_TARGETS)
 619 
 620 docs-javase-api-modulegraph: $(JAVASE_API_MODULEGRAPH_TARGETS)
 621 
 622 docs-reference-api-javadoc: $(REFERENCE_API_JAVADOC_TARGETS) $(REFERENCE_API_CUSTOM_TARGETS)
 623 
 624 docs-reference-api-modulegraph: $(REFERENCE_API_MODULEGRAPH_TARGETS)
 625 
 626 docs-jdk-specs: $(JDK_SPECS_TARGETS)
 627 
 628 docs-jdk-index: $(JDK_INDEX_TARGETS)
 629 
 630 docs-zip: $(ZIP_TARGETS)
< prev index next >