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 $(JDK_TOPDIR)/make/Tools.gmk
30
31 ################################################################################
32
33 # List of all possible directories for javadoc to look for sources
34 # Allow custom to overwrite.
35 JAVADOC_SOURCE_DIRS = \
36 $(SUPPORT_OUTPUTDIR)/gensrc/* \
37 $(addsuffix /*, $(IMPORT_MODULES_SRC)) \
38 $(JDK_TOPDIR)/src/*/$(OPENJDK_TARGET_OS)/classes \
39 $(JDK_TOPDIR)/src/*/$(OPENJDK_TARGET_OS_TYPE)/classes \
40 $(JDK_TOPDIR)/src/*/share/classes \
41 $(HOTSPOT_TOPDIR)/src/*/share/classes \
42 $(LANGTOOLS_TOPDIR)/src/*/share/classes \
43 $(NASHORN_TOPDIR)/src/*/share/classes \
44 $(CORBA_TOPDIR)/src/*/share/classes \
45 $(JAXP_TOPDIR)/src/*/share/classes \
46 $(JAXWS_TOPDIR)/src/*/share/classes \
47 $(SUPPORT_OUTPUTDIR)/rmic/* \
48 $(JDK_TOPDIR)/src/*/share/doc/stub \
49 #
157
158 # Speed up finding by filling cache
159 $(eval $(call FillCacheFind, $(wildcard $(JAVADOC_SOURCE_DIRS))))
160
161 # In order to get a specific ordering it's necessary to specify the total
162 # ordering of tags as the tags are otherwise ordered in order of definition.
163 DEFAULT_JAVADOC_TAGS := \
164 -tag beaninfo:X \
165 -tag revised:X \
166 -tag since.unbundled:X \
167 -tag spec:X \
168 -tag specdefault:X \
169 -tag Note:X \
170 -tag ToDo:X \
171 -tag 'apiNote:a:API Note:' \
172 -tag 'implSpec:a:Implementation Requirements:' \
173 -tag 'implNote:a:Implementation Note:' \
174 -tag param \
175 -tag return \
176 -tag throws \
177 -tag since \
178 -tag version \
179 -tag serialData \
180 -tag factory \
181 -tag see \
182 -tag 'jvms:a:See <cite>The Java™ Virtual Machine Specification</cite>:' \
183 -tag 'jls:a:See <cite>The Java™ Language Specification</cite>:' \
184 -taglet build.tools.taglet.Incubating \
185 -tagletpath $(BUILDTOOLS_OUTPUTDIR)/jdk_tools_classes \
186 #
187
188 DEFAULT_JAVADOC_OPTIONS := -XDignore.symbol.file=true -use -keywords -notimestamp \
189 -serialwarn -encoding ISO-8859-1 -breakiterator --system none
190
191 ################################################################################
192 # Setup make rules for running javadoc.
193 #
194 # Parameter 1 is the name of the rule. This name is used as variable prefix,
195 # and the targets generated are listed in a variable by that name. Note that
196 # the index.html file will work as a "touch file" for all the magnitude of
197 # files that are generated by javadoc.
198 #
199 # Remaining parameters are named arguments. These include:
200 # MODULES - Modules to include
201 # PACKAGES - Packages to include
202 # IS_CORE - Set to TRUE for the Core API package which needs special treatment
203 # API_ROOT - Where to base the documentation (jre or jdk)
204 # DEST_DIR - A directory relative to the API root
205 # OVERVIEW - Path to a html overview file
206 # TITLE - Default title to use for the more specific versions below
207 # WINDOW_TITLE - Title to use in -windowtitle. Computed from TITLE if empty.
208 # HEADER_TITLE - Title to use in -header. Computed from TITLE if empty.
209 # DOC_TITLE - Title to use in -doctitle. Computed from TITLE if empty.
210 # FIRST_COPYRIGHT_YEAR - First year this bundle was introduced
304
305 # If there are many packages, use an @-file...
306 ifneq ($$(word 17, $$($1_PACKAGES)), )
307 $1_PACKAGES_FILE := $$(SUPPORT_OUTPUTDIR)/docs/$1.packages
308 $1_PACKAGES_ARG := @$$($1_PACKAGES_FILE)
309 else
310 $1_PACKAGES_ARG := $$($1_PACKAGES)
311 endif
312
313 # The index.html which is a marker for all the output from javadoc.
314 $1_INDEX_FILE := $$(JAVADOC_OUTPUTDIR)/$$($1_OUTPUT_DIRNAME)/index.html
315
316 # Rule for actually running javadoc
317 $$($1_INDEX_FILE): $$(BUILD_TOOLS_JDK) $$($1_VARDEPS_FILE) $$($1_PACKAGE_DEPS) $$($1_DEPS)
318 $$(call LogWarn, Generating Javadoc from $$(words $$($1_PACKAGES)) package(s) for $$($1_OUTPUT_DIRNAME))
319 $$(call MakeDir, $$(@D))
320 ifneq ($$($1_PACKAGES_FILE), )
321 $$(eval $$(call ListPathsSafely, $1_PACKAGES, $$($1_PACKAGES_FILE)))
322 endif
323 $$(call ExecuteWithLog, $$(SUPPORT_OUTPUTDIR)/docs/$1.javadoc, \
324 $$($1_JAVA) -Djava.awt.headless=true $(NEW_JAVADOC) -d $$(@D) \
325 $$(DEFAULT_JAVADOC_TAGS) $$(DEFAULT_JAVADOC_OPTIONS) \
326 --module-source-path $$(call PathList, $$(JAVADOC_SOURCE_DIRS)) \
327 $$($1_OPTIONS) $$($1_PACKAGES_ARG))
328
329 # The output returned will be the index.html file
330 $1 := $$($1_INDEX_FILE)
331 endef
332
333 ################################################################################
334
335 $(eval $(call SetupJavadocGeneration, coredocs, \
336 MODULES := java.se.ee, \
337 PACKAGES := $(CORE_PACKAGES), \
338 IS_CORE := TRUE, \
339 OVERVIEW := $(JDK_TOPDIR)/src/java.base/share/classes/overview-core.html, \
340 WINDOW_TITLE := Java Platform SE $(VERSION_SPECIFICATION), \
341 HEADER_TITLE := Java™ Platform<br>Standard Ed. $(VERSION_SPECIFICATION), \
342 DOC_TITLE := Java™ Platform$(COMMA) Standard Edition \
343 $(VERSION_SPECIFICATION)<br>API Specification, \
344 FIRST_COPYRIGHT_YEAR := 1993, \
718 JAVADOC_ARCHIVE := $(JAVADOC_ARCHIVE_DIR)/$(JAVADOC_ARCHIVE_NAME)
719
720 $(JAVADOC_ARCHIVE): $(TARGETS) $(COPY_TARGETS)
721 $(call LogInfo, Compressing javadoc to single $(JAVADOC_ARCHIVE_NAME))
722 $(MKDIR) -p $(JAVADOC_ARCHIVE_DIR)
723 $(RM) -r $(JAVADOC_ARCHIVE_ASSEMBLY_DIR)
724 $(MKDIR) -p $(JAVADOC_ARCHIVE_ASSEMBLY_DIR)
725 all_roots=`$(FIND) $(JAVADOC_OUTPUTDIR) | $(GREP) index.html | grep -v old/doclet`; \
726 pushd $(JAVADOC_ARCHIVE_ASSEMBLY_DIR); \
727 for index_file in $${all_roots} ; do \
728 target_dir=`dirname $${index_file}`; \
729 name=`$(ECHO) $${target_dir} | $(SED) "s;/spec;;" | $(SED) "s;.*/;;"`; \
730 $(LN) -s $${target_dir} $${name}; \
731 done; \
732 $(ZIPEXE) -q -r $(JAVADOC_ARCHIVE) * ; \
733 popd ;
734
735 ZIP_TARGETS += $(JAVADOC_ARCHIVE)
736
737 ################################################################################
738
739 # Hook to include the corresponding custom file, if present.
740 $(eval $(call IncludeCustomExtension, , Javadoc.gmk))
741
742 ################################################################################
743
744 docs-javadoc: $(TARGETS)
745
746 docs-copy: $(COPY_TARGETS)
747
748 docs-zip: $(ZIP_TARGETS)
749
750 all: docs-javadoc docs-copy docs-zip
751
752 .PHONY: default all docs-javadoc docs-copy docs-zip
|
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 $(JDK_TOPDIR)/make/Tools.gmk
30 include $(JDK_TOPDIR)/make/ModuleTools.gmk
31
32 ################################################################################
33
34 # List of all possible directories for javadoc to look for sources
35 # Allow custom to overwrite.
36 JAVADOC_SOURCE_DIRS = \
37 $(SUPPORT_OUTPUTDIR)/gensrc/* \
38 $(addsuffix /*, $(IMPORT_MODULES_SRC)) \
39 $(JDK_TOPDIR)/src/*/$(OPENJDK_TARGET_OS)/classes \
40 $(JDK_TOPDIR)/src/*/$(OPENJDK_TARGET_OS_TYPE)/classes \
41 $(JDK_TOPDIR)/src/*/share/classes \
42 $(HOTSPOT_TOPDIR)/src/*/share/classes \
43 $(LANGTOOLS_TOPDIR)/src/*/share/classes \
44 $(NASHORN_TOPDIR)/src/*/share/classes \
45 $(CORBA_TOPDIR)/src/*/share/classes \
46 $(JAXP_TOPDIR)/src/*/share/classes \
47 $(JAXWS_TOPDIR)/src/*/share/classes \
48 $(SUPPORT_OUTPUTDIR)/rmic/* \
49 $(JDK_TOPDIR)/src/*/share/doc/stub \
50 #
158
159 # Speed up finding by filling cache
160 $(eval $(call FillCacheFind, $(wildcard $(JAVADOC_SOURCE_DIRS))))
161
162 # In order to get a specific ordering it's necessary to specify the total
163 # ordering of tags as the tags are otherwise ordered in order of definition.
164 DEFAULT_JAVADOC_TAGS := \
165 -tag beaninfo:X \
166 -tag revised:X \
167 -tag since.unbundled:X \
168 -tag spec:X \
169 -tag specdefault:X \
170 -tag Note:X \
171 -tag ToDo:X \
172 -tag 'apiNote:a:API Note:' \
173 -tag 'implSpec:a:Implementation Requirements:' \
174 -tag 'implNote:a:Implementation Note:' \
175 -tag param \
176 -tag return \
177 -tag throws \
178 -taglet build.tools.taglet.ModuleGraph \
179 -tag since \
180 -tag version \
181 -tag serialData \
182 -tag factory \
183 -tag see \
184 -tag 'jvms:a:See <cite>The Java™ Virtual Machine Specification</cite>:' \
185 -tag 'jls:a:See <cite>The Java™ Language Specification</cite>:' \
186 -taglet build.tools.taglet.Incubating \
187 -tagletpath $(BUILDTOOLS_OUTPUTDIR)/jdk_tools_classes \
188 #
189
190 DEFAULT_JAVADOC_OPTIONS := -XDignore.symbol.file=true -use -keywords -notimestamp \
191 -serialwarn -encoding ISO-8859-1 -breakiterator --system none
192
193 #
194 # TODO: this should be set by the configure option.
195 #
196 ifndef ENABLE_MODULE_GRAPH
197 ENABLE_MODULE_GRAPH=false
198 endif
199
200 ################################################################################
201 # Setup make rules for running javadoc.
202 #
203 # Parameter 1 is the name of the rule. This name is used as variable prefix,
204 # and the targets generated are listed in a variable by that name. Note that
205 # the index.html file will work as a "touch file" for all the magnitude of
206 # files that are generated by javadoc.
207 #
208 # Remaining parameters are named arguments. These include:
209 # MODULES - Modules to include
210 # PACKAGES - Packages to include
211 # IS_CORE - Set to TRUE for the Core API package which needs special treatment
212 # API_ROOT - Where to base the documentation (jre or jdk)
213 # DEST_DIR - A directory relative to the API root
214 # OVERVIEW - Path to a html overview file
215 # TITLE - Default title to use for the more specific versions below
216 # WINDOW_TITLE - Title to use in -windowtitle. Computed from TITLE if empty.
217 # HEADER_TITLE - Title to use in -header. Computed from TITLE if empty.
218 # DOC_TITLE - Title to use in -doctitle. Computed from TITLE if empty.
219 # FIRST_COPYRIGHT_YEAR - First year this bundle was introduced
313
314 # If there are many packages, use an @-file...
315 ifneq ($$(word 17, $$($1_PACKAGES)), )
316 $1_PACKAGES_FILE := $$(SUPPORT_OUTPUTDIR)/docs/$1.packages
317 $1_PACKAGES_ARG := @$$($1_PACKAGES_FILE)
318 else
319 $1_PACKAGES_ARG := $$($1_PACKAGES)
320 endif
321
322 # The index.html which is a marker for all the output from javadoc.
323 $1_INDEX_FILE := $$(JAVADOC_OUTPUTDIR)/$$($1_OUTPUT_DIRNAME)/index.html
324
325 # Rule for actually running javadoc
326 $$($1_INDEX_FILE): $$(BUILD_TOOLS_JDK) $$($1_VARDEPS_FILE) $$($1_PACKAGE_DEPS) $$($1_DEPS)
327 $$(call LogWarn, Generating Javadoc from $$(words $$($1_PACKAGES)) package(s) for $$($1_OUTPUT_DIRNAME))
328 $$(call MakeDir, $$(@D))
329 ifneq ($$($1_PACKAGES_FILE), )
330 $$(eval $$(call ListPathsSafely, $1_PACKAGES, $$($1_PACKAGES_FILE)))
331 endif
332 $$(call ExecuteWithLog, $$(SUPPORT_OUTPUTDIR)/docs/$1.javadoc, \
333 $$($1_JAVA) -Djava.awt.headless=true -DenableModuleGraph=$(ENABLE_MODULE_GRAPH) \
334 $(NEW_JAVADOC) -d $$(@D) \
335 $$(DEFAULT_JAVADOC_TAGS) $$(DEFAULT_JAVADOC_OPTIONS) \
336 --module-source-path $$(call PathList, $$(JAVADOC_SOURCE_DIRS)) \
337 $$($1_OPTIONS) $$($1_PACKAGES_ARG))
338
339 # The output returned will be the index.html file
340 $1 := $$($1_INDEX_FILE)
341 endef
342
343 ################################################################################
344
345 $(eval $(call SetupJavadocGeneration, coredocs, \
346 MODULES := java.se.ee, \
347 PACKAGES := $(CORE_PACKAGES), \
348 IS_CORE := TRUE, \
349 OVERVIEW := $(JDK_TOPDIR)/src/java.base/share/classes/overview-core.html, \
350 WINDOW_TITLE := Java Platform SE $(VERSION_SPECIFICATION), \
351 HEADER_TITLE := Java™ Platform<br>Standard Ed. $(VERSION_SPECIFICATION), \
352 DOC_TITLE := Java™ Platform$(COMMA) Standard Edition \
353 $(VERSION_SPECIFICATION)<br>API Specification, \
354 FIRST_COPYRIGHT_YEAR := 1993, \
728 JAVADOC_ARCHIVE := $(JAVADOC_ARCHIVE_DIR)/$(JAVADOC_ARCHIVE_NAME)
729
730 $(JAVADOC_ARCHIVE): $(TARGETS) $(COPY_TARGETS)
731 $(call LogInfo, Compressing javadoc to single $(JAVADOC_ARCHIVE_NAME))
732 $(MKDIR) -p $(JAVADOC_ARCHIVE_DIR)
733 $(RM) -r $(JAVADOC_ARCHIVE_ASSEMBLY_DIR)
734 $(MKDIR) -p $(JAVADOC_ARCHIVE_ASSEMBLY_DIR)
735 all_roots=`$(FIND) $(JAVADOC_OUTPUTDIR) | $(GREP) index.html | grep -v old/doclet`; \
736 pushd $(JAVADOC_ARCHIVE_ASSEMBLY_DIR); \
737 for index_file in $${all_roots} ; do \
738 target_dir=`dirname $${index_file}`; \
739 name=`$(ECHO) $${target_dir} | $(SED) "s;/spec;;" | $(SED) "s;.*/;;"`; \
740 $(LN) -s $${target_dir} $${name}; \
741 done; \
742 $(ZIPEXE) -q -r $(JAVADOC_ARCHIVE) * ; \
743 popd ;
744
745 ZIP_TARGETS += $(JAVADOC_ARCHIVE)
746
747 ################################################################################
748 # generate .dot files for module graphs
749
750 JAVADOC_MODULE_GRAPHS_DIR := $(SUPPORT_OUTPUTDIR)/docs/module-graphs
751 JAVADOC_MODULE_GRAPHS := $(JAVADOC_MODULE_GRAPHS_DIR)/java.se.dot
752 JAVADOC_MODULE_GRAPHS_ATTRIBUTES := $(JDK_TOPDIR)/make/src/classes/build/tools/jigsaw/javadoc-graphs.properties
753
754 $(JAVADOC_MODULE_GRAPHS): $(BUILD_JIGSAW_TOOLS) $(JAVADOC_MODULE_GRAPHS_ATTRIBUTES)
755 $(MKDIR) -p $(@D)
756 $(TOOL_GENGRAPHS) --spec --output $(JAVADOC_MODULE_GRAPHS_DIR) \
757 --dot-attributes $(JAVADOC_MODULE_GRAPHS_ATTRIBUTES)
758
759 MODULE_GRAPH_TARGETS += $(JAVADOC_MODULE_GRAPHS)
760
761 ################################################################################
762
763 # Hook to include the corresponding custom file, if present.
764 $(eval $(call IncludeCustomExtension, , Javadoc.gmk))
765
766 ################################################################################
767
768 docs-module-graphs: $(MODULE_GRAPH_TARGETS)
769
770 docs-javadoc: $(TARGETS)
771
772 docs-copy: $(COPY_TARGETS)
773
774 docs-zip: $(ZIP_TARGETS)
775
776 all: docs-module-graphs docs-javadoc docs-copy docs-zip
777
778 .PHONY: default all docs-module-graphs docs-javadoc docs-copy docs-zip
|