< prev index next >

make/Docs.gmk

Print this page




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


 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,..."


 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)


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


  87     -taglet build.tools.taglet.ModuleGraph \

  88     -tag since \
  89     -tag serialData \
  90     -tag factory \
  91     -tag see \
  92     -tag 'jvms:a:See <cite>The Java&trade; Virtual Machine Specification</cite>:' \
  93     -tag 'jls:a:See <cite>The Java&trade; Language Specification</cite>:' \
  94     -taglet build.tools.taglet.ExtLink \
  95     -taglet build.tools.taglet.Incubating \
  96     -tagletpath $(BUILDTOOLS_OUTPUTDIR)/jdk_tools_classes \
  97     $(CUSTOM_JAVADOC_TAGS) \
  98     #
  99 
 100 # The reference tags must stay stable to allow for comparisons across the
 101 # development cycle. If JAVADOC_TAGS needs to change, make sure that
 102 # REFERENCE_TAGS remains unchanged, by copying and hardcoding, if necessary.
 103 REFERENCE_TAGS := $(JAVADOC_TAGS)
 104 
 105 # Which doclint checks to ignore
 106 JAVADOC_DISABLED_DOCLINT := accessibility html missing syntax reference
 107 
 108 # The initial set of options for javadoc
 109 JAVADOC_OPTIONS := -use -keywords -notimestamp \
 110     -serialwarn -encoding ISO-8859-1 -docencoding UTF-8 -breakiterator \
 111     -splitIndex --system none -javafx --expand-requires transitive \
 112     --override-methods=summary
 113 


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









 151 JAVADOC_BOTTOM := \
 152     <a href="$(BUG_SUBMIT_URL)">Report a bug or suggest an enhancement</a><br> \
 153     For further API reference and developer documentation see the \
 154     <a href="$(JAVADOC_BASE_URL)" target="_blank">Java SE \
 155     Documentation</a>, which contains more detailed, \
 156     developer-targeted descriptions with conceptual overviews, definitions \
 157     of terms, workarounds, and working code examples.<br> \
 158     Java is a trademark or registered trademark of $(FULL_COMPANY_NAME) in \
 159     the US and other countries.<br> \
 160     <a href="$(COPYRIGHT_URL)">Copyright</a> \
 161     &copy; 1993, $(COPYRIGHT_YEAR), $(FULL_COMPANY_NAME), \
 162     $(COMPANY_ADDRESS).<br>All rights reserved. \
 163     Use is subject to <a href="$(LICENSE_URL)">license terms</a> and the \
 164     <a href="$(REDISTRIBUTION_URL)">documentation redistribution policy</a>. \
 165     $(DRAFT_MARKER_STR) <!-- Version $(VERSION_STRING) -->
 166 
 167 JAVADOC_TOP := \
 168     <div style="padding: 6px; text-align: center; font-size: 80%; \
 169     font-family: DejaVu Sans, Arial, Helvetica, sans-serif; \
 170     font-weight: normal;">$(DRAFT_TEXT)</div>
 171 
 172 ################################################################################
 173 # JDK javadoc titles/text snippets
 174 
 175 JDK_SHORT_NAME := Java SE $(VERSION_SPECIFICATION) &amp; JDK $(VERSION_SPECIFICATION)
 176 JDK_LONG_NAME := Java<sup>&reg;</sup> Platform, Standard Edition \
 177     &amp;&nbsp;Java&nbsp;Development&nbsp;Kit
 178 
 179 ################################################################################
 180 # Java SE javadoc titles/text snippets
 181 
 182 JAVASE_SHORT_NAME := Java SE $(VERSION_SPECIFICATION)
 183 JAVASE_LONG_NAME := Java<sup>&reg;</sup> Platform, Standard Edition
 184 
 185 ################################################################################


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

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


 483 # Copy the global resources, including the top-level redirect index.html
 484 GLOBAL_SPECS_RESOURCES_DIR := $(TOPDIR)/make/data/docs-resources/
 485 $(eval $(call SetupCopyFiles, COPY_GLOBAL_RESOURCES, \
 486     SRC := $(GLOBAL_SPECS_RESOURCES_DIR), \
 487     FILES := $(call FindFiles, $(GLOBAL_SPECS_RESOURCES_DIR)), \
 488     DEST := $(DOCS_OUTPUTDIR), \
 489 ))
 490 JDK_INDEX_TARGETS += $(COPY_GLOBAL_RESOURCES)
 491 
 492 # Copy the legal notices distributed with the docs bundle
 493 $(eval $(call SetupCopyFiles, COPY_DOCS_LEGAL_NOTICES, \
 494     SRC := $(TOPDIR)/src/jdk.javadoc/share/legal, \
 495     FILES := $(wildcard $(TOPDIR)/src/jdk.javadoc/share/legal/*), \
 496     DEST := $(DOCS_OUTPUTDIR)/legal, \
 497 ))
 498 JDK_INDEX_TARGETS += $(COPY_DOCS_LEGAL_NOTICES)
 499 
 500 ################################################################################
 501 # Copy JDK specs files
 502 
 503 # For all html documentation in $module/share/specs directories, copy it
 504 # unmodified
 505 
 506 ALL_MODULES := $(call FindAllModules)
 507 COPY_SPEC_FILTER := %.html %.gif %.jpg %.mib %.css
 508 
 509 $(foreach m, $(ALL_MODULES), \
 510   $(eval SPECS_$m := $(call FindModuleSpecsDirs, $m)) \
 511   $(foreach d, $(SPECS_$m), \
 512     $(if $(filter $(COPY_SPEC_FILTER), $(call FindFiles, $d)), \
 513       $(eval $(call SetupCopyFiles, COPY_$m, \
 514           SRC := $d, \
 515           FILES := $(filter $(COPY_SPEC_FILTER), $(call FindFiles, $d)), \
 516           DEST := $(DOCS_OUTPUTDIR)/specs/, \
 517       )) \
 518       $(eval JDK_SPECS_TARGETS += $(COPY_$m)) \
 519     ) \
 520   ) \
 521 )
 522 







































 523 ifeq ($(ENABLE_PANDOC), true)
 524   # For all markdown files in $module/share/specs directories, convert them to
 525   # html, if we have pandoc (otherwise we'll just skip this).
 526 
 527   GLOBAL_SPECS_DEFAULT_CSS_FILE := $(DOCS_OUTPUTDIR)/resources/jdk-default.css
 528 
 529   $(foreach m, $(ALL_MODULES), \
 530     $(eval SPECS_$m := $(call FindModuleSpecsDirs, $m)) \
 531     $(foreach d, $(SPECS_$m), \
 532       $(if $(filter %.md, $(call FindFiles, $d)), \
 533         $(eval $m_$d_NAME := SPECS_TO_HTML_$m_$(strip $(call RelativePath, $d, $(TOPDIR)))) \
 534         $(eval $(call SetupProcessMarkdown, $($m_$d_NAME), \


 535             SRC := $d, \
 536             FILES := $(filter %.md, $(call FindFiles, $d)), \
 537             DEST := $(DOCS_OUTPUTDIR)/specs/, \
 538             CSS := $(GLOBAL_SPECS_DEFAULT_CSS_FILE), \



 539         )) \
 540         $(eval JDK_SPECS_TARGETS += $($($m_$d_NAME))) \
 541       ) \
 542     ) \
 543   )
 544 
 545   # For all markdown files in $module/share/man directories, convert them to
 546   # html.
 547 
 548   # Create dynamic man pages from markdown using pandoc. We need
 549   # PANDOC_HTML_MANPAGE_FILTER, a wrapper around
 550   # PANDOC_HTML_MANPAGE_FILTER_JAVASCRIPT. This is created by buildtools-jdk.
 551 
 552   # We should also depend on the source javascript filter
 553   PANDOC_HTML_MANPAGE_FILTER_JAVASCRIPT := \
 554       $(TOPDIR)/make/scripts/pandoc-html-manpage-filter.js
 555 
 556   $(foreach m, $(ALL_MODULES), \
 557     $(eval MAN_$m := $(call FindModuleManDirs, $m)) \
 558     $(foreach d, $(MAN_$m), \
 559       $(if $(filter %.md, $(call FindFiles, $d)), \
 560         $(eval $m_$d_NAME := MAN_TO_HTML_$m_$(strip $(call RelativePath, $d, $(TOPDIR)))) \
 561         $(eval $(call SetupProcessMarkdown, $($m_$d_NAME), \
 562             SRC := $d, \
 563             FILES := $(filter %.md, $(call FindFiles, $d)), \
 564             DEST := $(DOCS_OUTPUTDIR)/specs/man, \
 565             FILTER := $(PANDOC_HTML_MANPAGE_FILTER), \
 566             CSS := $(GLOBAL_SPECS_DEFAULT_CSS_FILE), \
 567             REPLACEMENTS := @@VERSION_SHORT@@ => $(VERSION_SHORT), \


 568             EXTRA_DEPS := $(PANDOC_HTML_MANPAGE_FILTER) \
 569                 $(PANDOC_HTML_MANPAGE_FILTER_JAVASCRIPT), \

 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 >