comparison make/Docs.gmk @ 2639:7df4f16bfa8f

8182408: Simplify the API-specification overview page Reviewed-by: erikj, mchung, jrose, alanb
author mr
date Mon, 19 Jun 2017 18:20:42 +0200
parents ce42e2c57dc7
children 985eae459953
comparison
equal deleted inserted replaced
7:e7bdb2a3df74 8:c0ad3b7f3f65
114 114
115 ################################################################################ 115 ################################################################################
116 # General text snippets 116 # General text snippets
117 117
118 FULL_COMPANY_NAME := Oracle and/or its affiliates 118 FULL_COMPANY_NAME := Oracle and/or its affiliates
119 COMPANY_ADDRESS := 500 Oracle Parkway<br>Redwood Shores, CA 94065 USA 119 COMPANY_ADDRESS := 500 Oracle Parkway, Redwood Shores, CA 94065 USA
120 120
121 JAVA_PLATFORM := Java&trade; Platform 121 JAVA_PLATFORM := Java Platform
122 122
123 ifeq ($(IS_DRAFT), true) 123 ifeq ($(IS_DRAFT), true)
124 DRAFT_MARKER_STR := <br><strong>DRAFT $(VERSION_STRING)</strong> 124 DRAFT_MARKER_STR := <br><strong>DRAFT $(VERSION_STRING)</strong>
125 ifeq ($(VERSION_BUILD), 0) 125 ifeq ($(VERSION_BUILD), 0)
126 DRAFT_MARKER_TITLE := [ad-hoc build] 126 DRAFT_MARKER_TITLE := [ad-hoc build]
127 else 127 else
128 DRAFT_MARKER_TITLE := [build $(VERSION_BUILD)] 128 DRAFT_MARKER_TITLE := [build $(VERSION_BUILD)]
129 endif 129 endif
130 DRAFT_TEXT := Please note that the specifications and other information \ 130 DRAFT_TEXT := This specification is not final and is subject to change. \
131 contained herein are not final and are subject to change. The \ 131 Use is subject to <a href="$(LICENSE_URL)">license terms</a>.
132 information is being made available to you solely for purpose of \
133 evaluation.
134 endif 132 endif
135 133
136 JAVADOC_BOTTOM := \ 134 JAVADOC_BOTTOM := \
137 <span style="font-size:smaller"> \ 135 <a href="$(BUG_SUBMIT_URL)">Report a bug or suggest an enhancement</a><br> \
138 <a href="$(BUG_SUBMIT_URL)">Submit a bug or feature</a><br> \ 136 For further API reference and developer documentation see the \
139 For further API reference and developer documentation, see \
140 <a href="$(JAVADOC_BASE_URL)" target="_blank">Java SE \ 137 <a href="$(JAVADOC_BASE_URL)" target="_blank">Java SE \
141 Documentation</a>. That documentation contains more detailed, \ 138 Documentation</a>, which contains more detailed, \
142 developer-targeted descriptions, with conceptual overviews, definitions \ 139 developer-targeted descriptions with conceptual overviews, definitions \
143 of terms, workarounds, and working code examples.<br> \ 140 of terms, workarounds, and working code examples.<br> \
144 Java is a trademark or registered trademark of $(FULL_COMPANY_NAME) in \ 141 Java is a trademark or registered trademark of $(FULL_COMPANY_NAME) in \
145 the US and other countries.<br> \ 142 the US and other countries.<br> \
146 <a href="$(COPYRIGHT_URL)">Copyright</a> \ 143 <a href="$(COPYRIGHT_URL)">Copyright</a> \
147 &copy; 1993, $(COPYRIGHT_YEAR), $(FULL_COMPANY_NAME). \ 144 &copy; 1993, $(COPYRIGHT_YEAR), $(FULL_COMPANY_NAME), \
148 $(COMPANY_ADDRESS). All rights reserved. \ 145 $(COMPANY_ADDRESS).<br>All rights reserved. \
149 Use is subject to <a href="$(LICENSE_URL)">license terms</a>. Also see the \ 146 Use is subject to <a href="$(LICENSE_URL)">license terms</a> and the \
150 <a href="$(REDISTRIBUTION_URL)">documentation redistribution policy</a>. \ 147 <a href="$(REDISTRIBUTION_URL)">documentation redistribution policy</a>. \
151 $(DRAFT_MARKER_STR)</span> 148 $(DRAFT_MARKER_STR) <!-- Version $(VERSION_STRING) -->
149
152 150
153 JAVADOC_TOP := \ 151 JAVADOC_TOP := \
154 <div style="background-color: $(HASH)EEEEEE"><div style="padding: 6px; \ 152 <div style="padding: 6px; text-align: center; font-size: 80%; \
155 margin-top: 2px; margin-bottom: 6px; margin-left: 6px; margin-right: \ 153 font-family: DejaVu Sans, Arial, Helvetica, sans-serif; \
156 6px; text-align: justify; font-size: 80%; font-family: Helvetica, Arial, \ 154 font-weight: normal;">$(DRAFT_TEXT)</div>
157 sans-serif; font-weight: normal;">$(DRAFT_TEXT)</div></div>
158 155
159 ################################################################################ 156 ################################################################################
160 # JDK javadoc titles/text snippets 157 # JDK javadoc titles/text snippets
161 158
162 JDK_SHORT_NAME := JDK&trade; $(VERSION_SPECIFICATION) 159 JDK_SHORT_NAME := Java SE $(VERSION_SPECIFICATION) &amp; JDK $(VERSION_SPECIFICATION)
163 JDK_LONG_NAME := Standard Edition Development Kit (JDK&trade;) $(VERSION_SPECIFICATION) 160 JDK_LONG_NAME := Java<sup>&reg;</sup> Platform, Standard Edition \
161 <span style="white-space: nowrap;">&amp; Java Development Kit</span>
164 162
165 ################################################################################ 163 ################################################################################
166 # Java SE javadoc titles/text snippets 164 # Java SE javadoc titles/text snippets
167 165
168 JAVASE_SHORT_NAME := SE $(VERSION_SPECIFICATION) 166 JAVASE_SHORT_NAME := Java SE $(VERSION_SPECIFICATION)
169 JAVASE_LONG_NAME := Standard Edition $(VERSION_SPECIFICATION) 167 JAVASE_LONG_NAME := Java<sup>&reg;</sup> Platform, Standard Edition
170 168
171 ################################################################################ 169 ################################################################################
172 # Functions 170 # Functions
173 171
174 # Helper function for creating a png file from a dot file generated by the 172 # Helper function for creating a png file from a dot file generated by the
197 # param 1: SetupJavadocGeneration namespace ($1) 195 # param 1: SetupJavadocGeneration namespace ($1)
198 define create_overview_file 196 define create_overview_file
199 $1_OVERVIEW_TEXT := \ 197 $1_OVERVIEW_TEXT := \
200 <!DOCTYPE html> \ 198 <!DOCTYPE html> \
201 <html><head></head><body> \ 199 <html><head></head><body> \
202 <p>This document is the API specification for $$($1_FULL_NAME).</p> \
203 # 200 #
204 ifneq ($$($1_GROUPS),) 201 ifneq ($$($1_GROUPS),)
205 $1_OVERVIEW_TEXT += \ 202 $1_OVERVIEW_TEXT += \
206 <dl> \ 203 <p>This document is divided into \
207 # 204 $$(subst 2,two,$$(subst 3,three,$$(words $$($1_GROUPS)))) sections:</p> \
205 <blockquote><dl> \
206 #
208 $1_OVERVIEW_TEXT += $$(foreach g, $$($1_GROUPS), \ 207 $1_OVERVIEW_TEXT += $$(foreach g, $$($1_GROUPS), \
209 <dt><a href="\#$$g">$$($$g_GROUP_NAME)</a></dt> \ 208 <dt style="margin-top: 8px;"><a href="\#$$g">$$($$g_GROUP_NAME)</a></dt> \
210 <dd>$$($$g_GROUP_DESCRIPTION)</dt> \ 209 <dd style="margin-top: 8px;">$$($$g_GROUP_DESCRIPTION)</dt> \
211 ) 210 )
212 $1_OVERVIEW_TEXT += \ 211 $1_OVERVIEW_TEXT += \
213 </dl> \ 212 </dl><blockquote> \
214 #
215 endif
216 ifeq ($$(IS_DRAFT), true)
217 $1_OVERVIEW_TEXT += \
218 <p><strong>$$(DRAFT_TEXT)</strong></p> \
219 # 213 #
220 endif 214 endif
221 $1_OVERVIEW_TEXT += \ 215 $1_OVERVIEW_TEXT += \
222 </body></html> \ 216 </body></html> \
223 # 217 #
271 265
272 # Create a string like "-Xdoclint:all,-syntax,-html,..." 266 # Create a string like "-Xdoclint:all,-syntax,-html,..."
273 $1_OPTIONS += -Xdoclint:all,$$(call CommaList, $$(addprefix -, \ 267 $1_OPTIONS += -Xdoclint:all,$$(call CommaList, $$(addprefix -, \
274 $$(JAVADOC_DISABLED_DOCLINT))) 268 $$(JAVADOC_DISABLED_DOCLINT)))
275 269
276 $1_FULL_NAME := $$(JAVA_PLATFORM), $$($1_LONG_NAME) \ 270 $1_DOC_TITLE := $$($1_LONG_NAME)<br>Version $$(VERSION_SPECIFICATION) API Specification
277 $$(DRAFT_MARKER_TITLE) 271 $1_WINDOW_TITLE := $$(subst &amp;,&,$$($1_SHORT_NAME)) \
278 $1_DOC_TITLE := $$($1_FULL_NAME)<br>API Specification
279 $1_WINDOW_TITLE := $$(subst &trade;,,$$(JAVA_PLATFORM) $$($1_SHORT_NAME)) \
280 $$(DRAFT_MARKER_TITLE) 272 $$(DRAFT_MARKER_TITLE)
281 $1_HEADER_TITLE := <strong>$$(JAVA_PLATFORM)<br>$$($1_SHORT_NAME)</strong> \ 273 ifeq ($(VERSION_IS_GA), true) # Workaround stylesheet bug
282 $$(DRAFT_MARKER_STR) 274 $1_HEADER_PAD := 14
275 else
276 $1_HEADER_PAD := 9
277 endif
278 $1_HEADER_TITLE := <div style="margin-top: $$($1_HEADER_PAD)px;"><strong>$$($1_SHORT_NAME)</strong> \
279 $$(DRAFT_MARKER_STR)</div>
283 280
284 $1_OPTIONS += -doctitle '$$($1_DOC_TITLE)' 281 $1_OPTIONS += -doctitle '$$($1_DOC_TITLE)'
285 $1_OPTIONS += -windowtitle '$$($1_WINDOW_TITLE)' 282 $1_OPTIONS += -windowtitle '$$($1_WINDOW_TITLE)'
286 $1_OPTIONS += -header '$$($1_HEADER_TITLE)' 283 $1_OPTIONS += -header '$$($1_HEADER_TITLE)'
287 $1_OPTIONS += -bottom '$$(JAVADOC_BOTTOM)' 284 $1_OPTIONS += -bottom '$$(JAVADOC_BOTTOM)'
371 # Define the groups of the JDK API documentation 368 # Define the groups of the JDK API documentation
372 JavaSE_GROUP_NAME := Java SE 369 JavaSE_GROUP_NAME := Java SE
373 JavaSE_GROUP_MODULES := $(call ColonList, $(sort java.se.ee \ 370 JavaSE_GROUP_MODULES := $(call ColonList, $(sort java.se.ee \
374 $(call FindTransitiveIndirectDepsForModules, java.se.ee))) 371 $(call FindTransitiveIndirectDepsForModules, java.se.ee)))
375 JavaSE_GROUP_DESCRIPTION := \ 372 JavaSE_GROUP_DESCRIPTION := \
376 The Java Platform, Standard Edition ("Java SE") APIs define the core Java \ 373 The Java Platform, Standard Edition (Java SE) APIs define the core Java \
377 platform for general-purpose computing. These APIs are in modules with \ 374 platform for general-purpose computing. These APIs are in modules whose \
378 names starting with the string "java.". \ 375 names start with {@code java}. \
379 # 376 #
380 JDK_GROUPS += JavaSE 377 JDK_GROUPS += JavaSE
381 378
382 JDK_GROUP_NAME := JDK 379 JDK_GROUP_NAME := JDK
383 JDK_GROUP_MODULES := jdk.* 380 JDK_GROUP_MODULES := jdk.*
384 JDK_GROUP_DESCRIPTION := \ 381 JDK_GROUP_DESCRIPTION := \
385 The Java Development Kit ("JDK") APIs define an implementation of the Java \ 382 The Java Development Kit (JDK) APIs are specific to the JDK and will not \
386 SE Platform which may include platform-specific details. These APIs are in \ 383 necessarily be available in all implementations of the Java SE Platform. \
387 modules with names starting with the string "jdk.". \ 384 These APIs are in modules whose names start with {@code jdk}. \
388 # 385 #
389 JDK_GROUPS += JDK 386 JDK_GROUPS += JDK
390 387
391 # If we are importing JavaFX, we need a JavaFX group. In an ideal world, this 388 # If we are importing JavaFX, we need a JavaFX group. In an ideal world, this
392 # would have been abstracted away to a more proper generic handling of imported 389 # would have been abstracted away to a more proper generic handling of imported
393 # modules. 390 # modules.
394 ifneq ($(findstring javafx., $(IMPORTED_MODULES)), ) 391 ifneq ($(findstring javafx., $(IMPORTED_MODULES)), )
395 JavaFX_GROUP_NAME := JavaFX 392 JavaFX_GROUP_NAME := JavaFX
396 JavaFX_GROUP_MODULES := javafx.* 393 JavaFX_GROUP_MODULES := javafx.*
397 JavaFX_GROUP_DESCRIPTION := \ 394 JavaFX_GROUP_DESCRIPTION := \
398 The JavaFX APIs define a set of user interface (UI) controls, graphics, \ 395 The JavaFX APIs define a set of user-interface controls, graphics, \
399 media, and web packages for developing rich client applications. These \ 396 media, and web packages for developing rich client applications. These \
400 APIs are in modules with names starting with the string "javafx.". \ 397 APIs are in modules whose names start with {@code javafx}. \
401 # 398 #
402 JDK_GROUPS += JavaFX 399 JDK_GROUPS += JavaFX
403 endif 400 endif
404 401
405 # All modules to have docs generated by docs-jdk-api target 402 # All modules to have docs generated by docs-jdk-api target
417 # JDK_API_MODULEGRAPH_TARGETS. 414 # JDK_API_MODULEGRAPH_TARGETS.
418 415
419 ################################################################################ 416 ################################################################################
420 # Setup generation of the Java SE API documentation (javadoc + modulegraph) 417 # Setup generation of the Java SE API documentation (javadoc + modulegraph)
421 418
422 # The Java SE module scope is just java.se.ee and it's transitive indirect 419 # The Java SE module scope is just java.se.ee and its transitive indirect
423 # exports. 420 # exports.
424 JAVASE_MODULES := java.se.ee 421 JAVASE_MODULES := java.se.ee
425 422
426 $(eval $(call SetupApiDocsGeneration, JAVASE_API, \ 423 $(eval $(call SetupApiDocsGeneration, JAVASE_API, \
427 MODULES := $(JAVASE_MODULES), \ 424 MODULES := $(JAVASE_MODULES), \