1 /*
2 * Copyright (c) 1998, 2019, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26 package jdk.javadoc.internal.doclets.formats.html;
27
28 import jdk.javadoc.internal.doclets.formats.html.markup.BodyContents;
29 import jdk.javadoc.internal.doclets.formats.html.markup.ContentBuilder;
30 import jdk.javadoc.internal.doclets.formats.html.markup.HtmlStyle;
31 import jdk.javadoc.internal.doclets.formats.html.markup.HtmlTag;
32 import jdk.javadoc.internal.doclets.formats.html.markup.HtmlTree;
33 import jdk.javadoc.internal.doclets.formats.html.markup.Navigation;
34 import jdk.javadoc.internal.doclets.formats.html.markup.Navigation.PageMode;
35 import jdk.javadoc.internal.doclets.formats.html.markup.StringContent;
36 import jdk.javadoc.internal.doclets.toolkit.Content;
37 import jdk.javadoc.internal.doclets.toolkit.util.DocFileIOException;
38 import jdk.javadoc.internal.doclets.toolkit.util.DocPath;
39 import jdk.javadoc.internal.doclets.toolkit.util.DocPaths;
40
41
42 /**
43 * Generate the Help File for the generated API documentation. The help file
44 * contents are helpful for browsing the generated documentation.
45 *
46 * <p><b>This is NOT part of any supported API.
47 * If you write code that depends on this, you do so at your own risk.
48 * This code and its internal interfaces are subject to change or
49 * deletion without notice.</b>
50 */
51 public class HelpWriter extends HtmlDocletWriter {
52
53 private final Navigation navBar;
54
55 private final String[][] SEARCH_EXAMPLES = {
56 {"j.l.obj", "\"java.lang.Object\""},
57 {"InpStr", "\"java.io.InputStream\""},
58 {"HM.cK", "\"java.util.HashMap.containsKey(Object)\""}
59 };
60
61 /**
62 * Constructor to construct HelpWriter object.
63 * @param configuration the configuration
64 * @param filename File to be generated.
65 */
66 public HelpWriter(HtmlConfiguration configuration,
67 DocPath filename) {
68 super(configuration, filename);
69 this.navBar = new Navigation(null, configuration, PageMode.HELP, path);
70 }
71
72 /**
73 * Construct the HelpWriter object and then use it to generate the help
74 * file. The name of the generated file is "help-doc.html". The help file
75 * will get generated if and only if "-helpfile" and "-nohelp" is not used
76 * on the command line.
77 *
78 * @param configuration the configuration
79 * @throws DocFileIOException if there is a problem while generating the documentation
80 */
81 public static void generate(HtmlConfiguration configuration) throws DocFileIOException {
82 DocPath filename = DocPaths.HELP_DOC;
83 HelpWriter helpgen = new HelpWriter(configuration, filename);
84 helpgen.generateHelpFile();
85 }
86
87 /**
88 * Generate the help file contents.
89 *
90 * @throws DocFileIOException if there is a problem while generating the documentation
91 */
92 protected void generateHelpFile() throws DocFileIOException {
93 String title = resources.getText("doclet.Window_Help_title");
94 HtmlTree body = getBody(getWindowTitle(title));
95 Content headerContent = new ContentBuilder();
96 addTop(headerContent);
97 navBar.setUserHeader(getUserHeaderFooter(true));
98 headerContent.add(navBar.getContent(true));
99 ContentBuilder helpFileContent = new ContentBuilder();
100 addHelpFileContents(helpFileContent);
101 HtmlTree footer = HtmlTree.FOOTER();
102 navBar.setUserFooter(getUserHeaderFooter(false));
103 footer.add(navBar.getContent(false));
104 addBottom(footer);
105 body.add(new BodyContents()
106 .setHeader(headerContent)
107 .addMainContent(helpFileContent)
108 .setFooter(footer)
109 .toContent());
110 printHtmlDocument(null, "help", body);
111 }
112
113 /**
114 * Add the help file contents from the resource file to the content tree. While adding the
115 * help file contents it also keeps track of user options. If "-notree"
116 * is used, then the "overview-tree.html" will not get added and hence
117 * help information also will not get added.
118 *
119 * @param contentTree the content tree to which the help file contents will be added
120 */
121 protected void addHelpFileContents(Content contentTree) {
122 // Heading
123 Content heading = HtmlTree.HEADING(Headings.PAGE_TITLE_HEADING, false, HtmlStyle.title,
124 contents.getContent("doclet.help.main_heading"));
125 Content div = HtmlTree.DIV(HtmlStyle.header, heading);
126 Content intro = HtmlTree.DIV(HtmlStyle.subTitle,
127 contents.getContent("doclet.help.intro"));
128 div.add(intro);
129 contentTree.add(div);
130 HtmlTree htmlTree;
131 HtmlTree ul = new HtmlTree(HtmlTag.UL);
132 ul.setStyle(HtmlStyle.blockList);
133
134 // Overview
135 if (configuration.createoverview) {
136 Content overviewHeading = HtmlTree.HEADING(Headings.CONTENT_HEADING,
137 contents.overviewLabel);
138 htmlTree = HtmlTree.SECTION(HtmlStyle.helpSection, overviewHeading);
139 String overviewKey = configuration.showModules
140 ? "doclet.help.overview.modules.body"
141 : "doclet.help.overview.packages.body";
142 Content overviewLink = links.createLink(
143 DocPaths.INDEX, resources.getText("doclet.Overview"));
144 Content overviewBody = contents.getContent(overviewKey, overviewLink);
145 Content overviewPara = HtmlTree.P(overviewBody);
146 htmlTree.add(overviewPara);
147 ul.add(HtmlTree.LI(HtmlStyle.blockList, htmlTree));
148 }
149
150 // Module
151 if (configuration.showModules) {
152 Content moduleHead = HtmlTree.HEADING(Headings.CONTENT_HEADING,
153 contents.moduleLabel);
154 htmlTree = HtmlTree.SECTION(HtmlStyle.helpSection, moduleHead);
155 Content moduleIntro = contents.getContent("doclet.help.module.intro");
156 Content modulePara = HtmlTree.P(moduleIntro);
157 htmlTree.add(modulePara);
158 HtmlTree ulModule = new HtmlTree(HtmlTag.UL);
159 ulModule.add(HtmlTree.LI(contents.packagesLabel));
160 ulModule.add(HtmlTree.LI(contents.modulesLabel));
161 ulModule.add(HtmlTree.LI(contents.servicesLabel));
162 htmlTree.add(ulModule);
163 ul.add(HtmlTree.LI(HtmlStyle.blockList, htmlTree));
164 }
165
166 // Package
167 Content packageHead = HtmlTree.HEADING(Headings.CONTENT_HEADING,
168 contents.packageLabel);
169 htmlTree = HtmlTree.SECTION(HtmlStyle.helpSection, packageHead);
170 Content packageIntro = contents.getContent("doclet.help.package.intro");
171 Content packagePara = HtmlTree.P(packageIntro);
172 htmlTree.add(packagePara);
173 HtmlTree ulPackage = new HtmlTree(HtmlTag.UL);
174 ulPackage.add(HtmlTree.LI(contents.interfaces));
175 ulPackage.add(HtmlTree.LI(contents.classes));
176 ulPackage.add(HtmlTree.LI(contents.enums));
177 ulPackage.add(HtmlTree.LI(contents.exceptions));
178 ulPackage.add(HtmlTree.LI(contents.errors));
179 ulPackage.add(HtmlTree.LI(contents.annotationTypes));
180 htmlTree.add(ulPackage);
181 ul.add(HtmlTree.LI(HtmlStyle.blockList, htmlTree));
182
183 // Class/interface
184 Content classHead = HtmlTree.HEADING(Headings.CONTENT_HEADING,
185 contents.getContent("doclet.help.class_interface.head"));
186 htmlTree = HtmlTree.SECTION(HtmlStyle.helpSection, classHead);
187 Content classIntro = contents.getContent("doclet.help.class_interface.intro");
188 Content classPara = HtmlTree.P(classIntro);
189 htmlTree.add(classPara);
190 HtmlTree ul1 = new HtmlTree(HtmlTag.UL);
191 ul1.add(HtmlTree.LI(contents.getContent("doclet.help.class_interface.inheritance_diagram")));
192 ul1.add(HtmlTree.LI(contents.getContent("doclet.help.class_interface.subclasses")));
193 ul1.add(HtmlTree.LI(contents.getContent("doclet.help.class_interface.subinterfaces")));
194 ul1.add(HtmlTree.LI(contents.getContent("doclet.help.class_interface.implementations")));
195 ul1.add(HtmlTree.LI(contents.getContent("doclet.help.class_interface.declaration")));
196 ul1.add(HtmlTree.LI(contents.getContent("doclet.help.class_interface.description")));
197 htmlTree.add(ul1);
198 htmlTree.add(new HtmlTree(HtmlTag.BR));
199 HtmlTree ul2 = new HtmlTree(HtmlTag.UL);
200 ul2.add(HtmlTree.LI(contents.nestedClassSummary));
201 ul2.add(HtmlTree.LI(contents.fieldSummaryLabel));
202 ul2.add(HtmlTree.LI(contents.propertySummaryLabel));
203 ul2.add(HtmlTree.LI(contents.constructorSummaryLabel));
204 ul2.add(HtmlTree.LI(contents.methodSummary));
205 htmlTree.add(ul2);
206 htmlTree.add(new HtmlTree(HtmlTag.BR));
207 HtmlTree ul3 = new HtmlTree(HtmlTag.UL);
208 ul3.add(HtmlTree.LI(contents.fieldDetailsLabel));
209 ul3.add(HtmlTree.LI(contents.propertyDetailsLabel));
210 ul3.add(HtmlTree.LI(contents.constructorDetailsLabel));
211 ul3.add(HtmlTree.LI(contents.methodDetailLabel));
212 htmlTree.add(ul3);
213 Content classSummary = contents.getContent("doclet.help.class_interface.summary");
214 Content para = HtmlTree.P(classSummary);
215 htmlTree.add(para);
216 ul.add(HtmlTree.LI(HtmlStyle.blockList, htmlTree));
217
218 // Annotation Types
219 Content aHead = HtmlTree.HEADING(Headings.CONTENT_HEADING,
220 contents.annotationType);
221 htmlTree = HtmlTree.SECTION(HtmlStyle.helpSection, aHead);
222 Content aIntro = contents.getContent("doclet.help.annotation_type.intro");
223 Content aPara = HtmlTree.P(aIntro);
224 htmlTree.add(aPara);
225 HtmlTree aul = new HtmlTree(HtmlTag.UL);
226 aul.add(HtmlTree.LI(contents.getContent("doclet.help.annotation_type.declaration")));
227 aul.add(HtmlTree.LI(contents.getContent("doclet.help.annotation_type.description")));
228 aul.add(HtmlTree.LI(contents.annotateTypeRequiredMemberSummaryLabel));
229 aul.add(HtmlTree.LI(contents.annotateTypeOptionalMemberSummaryLabel));
230 aul.add(HtmlTree.LI(contents.annotationTypeMemberDetail));
231 htmlTree.add(aul);
232 ul.add(HtmlTree.LI(HtmlStyle.blockList, htmlTree));
233
234 // Enums
235 Content enumHead = HtmlTree.HEADING(Headings.CONTENT_HEADING, contents.enum_);
236 htmlTree = HtmlTree.SECTION(HtmlStyle.helpSection, enumHead);
237 Content eIntro = contents.getContent("doclet.help.enum.intro");
238 Content enumPara = HtmlTree.P(eIntro);
239 htmlTree.add(enumPara);
240 HtmlTree eul = new HtmlTree(HtmlTag.UL);
241 eul.add(HtmlTree.LI(contents.getContent("doclet.help.enum.declaration")));
242 eul.add(HtmlTree.LI(contents.getContent("doclet.help.enum.definition")));
243 eul.add(HtmlTree.LI(contents.enumConstantSummary));
244 eul.add(HtmlTree.LI(contents.enumConstantDetailLabel));
245 htmlTree.add(eul);
246 ul.add(HtmlTree.LI(HtmlStyle.blockList, htmlTree));
247
248 // Class Use
249 if (configuration.classuse) {
250 Content useHead = HtmlTree.HEADING(Headings.CONTENT_HEADING,
251 contents.getContent("doclet.help.use.head"));
252 htmlTree = HtmlTree.SECTION(HtmlStyle.helpSection, useHead);
253 Content useBody = contents.getContent("doclet.help.use.body");
254 Content usePara = HtmlTree.P(useBody);
255 htmlTree.add(usePara);
256 ul.add(HtmlTree.LI(HtmlStyle.blockList, htmlTree));
257 }
258
259 // Tree
260 if (configuration.createtree) {
261 Content treeHead = HtmlTree.HEADING(Headings.CONTENT_HEADING,
262 contents.getContent("doclet.help.tree.head"));
263 htmlTree = HtmlTree.SECTION(HtmlStyle.helpSection, treeHead);
264 Content treeIntro = contents.getContent("doclet.help.tree.intro",
265 links.createLink(DocPaths.OVERVIEW_TREE,
266 resources.getText("doclet.Class_Hierarchy")),
267 HtmlTree.CODE(new StringContent("java.lang.Object")));
268 Content treePara = HtmlTree.P(treeIntro);
269 htmlTree.add(treePara);
270 HtmlTree tul = new HtmlTree(HtmlTag.UL);
271 tul.add(HtmlTree.LI(contents.getContent("doclet.help.tree.overview")));
272 tul.add(HtmlTree.LI(contents.getContent("doclet.help.tree.package")));
273 htmlTree.add(tul);
274 ul.add(HtmlTree.LI(HtmlStyle.blockList, htmlTree));
275 }
276
277 // Deprecated
278 if (!(configuration.nodeprecatedlist || configuration.nodeprecated)) {
279 Content dHead = HtmlTree.HEADING(Headings.CONTENT_HEADING,
280 contents.deprecatedAPI);
281 htmlTree = HtmlTree.SECTION(HtmlStyle.helpSection, dHead);
282 Content deprBody = contents.getContent("doclet.help.deprecated.body",
283 links.createLink(DocPaths.DEPRECATED_LIST,
284 resources.getText("doclet.Deprecated_API")));
285 Content dPara = HtmlTree.P(deprBody);
286 htmlTree.add(dPara);
287 ul.add(HtmlTree.LI(HtmlStyle.blockList, htmlTree));
288 }
289
290 // Index
291 if (configuration.createindex) {
292 Content indexlink;
293 if (configuration.splitindex) {
294 indexlink = links.createLink(DocPaths.INDEX_FILES.resolve(DocPaths.indexN(1)),
295 resources.getText("doclet.Index"));
296 } else {
297 indexlink = links.createLink(DocPaths.INDEX_ALL,
298 resources.getText("doclet.Index"));
299 }
300 Content indexHead = HtmlTree.HEADING(Headings.CONTENT_HEADING,
301 contents.getContent("doclet.help.index.head"));
302 htmlTree = HtmlTree.SECTION(HtmlStyle.helpSection, indexHead);
303 Content indexBody = contents.getContent("doclet.help.index.body", indexlink);
304 Content indexPara = HtmlTree.P(indexBody);
305 htmlTree.add(indexPara);
306 ul.add(HtmlTree.LI(HtmlStyle.blockList, htmlTree));
307 }
308
309 // Serialized Form
310 Content sHead = HtmlTree.HEADING(Headings.CONTENT_HEADING,
311 contents.serializedForm);
312 htmlTree = HtmlTree.SECTION(HtmlStyle.helpSection, sHead);
313 Content serialBody = contents.getContent("doclet.help.serial_form.body");
314 Content serialPara = HtmlTree.P(serialBody);
315 htmlTree.add(serialPara);
316 ul.add(HtmlTree.LI(HtmlStyle.blockList, htmlTree));
317
318 // Constant Field Values
319 Content constHead = HtmlTree.HEADING(Headings.CONTENT_HEADING,
320 contents.constantsSummaryTitle);
321 htmlTree = HtmlTree.SECTION(HtmlStyle.helpSection, constHead);
322 Content constantsBody = contents.getContent("doclet.help.constants.body",
323 links.createLink(DocPaths.CONSTANT_VALUES,
324 resources.getText("doclet.Constants_Summary")));
325 Content constPara = HtmlTree.P(constantsBody);
326 htmlTree.add(constPara);
327 ul.add(HtmlTree.LI(HtmlStyle.blockList, htmlTree));
328
329 // Search
330 Content searchHead = HtmlTree.HEADING(Headings.CONTENT_HEADING,
331 contents.getContent("doclet.help.search.head"));
332 htmlTree = HtmlTree.SECTION(HtmlStyle.helpSection, searchHead);
333 Content searchIntro = HtmlTree.P(contents.getContent("doclet.help.search.intro"));
334 Content searchExamples = new HtmlTree(HtmlTag.UL);
335 for (String[] example : SEARCH_EXAMPLES) {
336 searchExamples.add(HtmlTree.LI(
337 contents.getContent("doclet.help.search.example",
338 HtmlTree.CODE(new StringContent(example[0])), example[1])));
339 }
340 Content searchSpecLink = HtmlTree.A(
341 resources.getText("doclet.help.search.spec.url", Runtime.version().feature()),
342 contents.getContent("doclet.help.search.spec.title"));
343 Content searchRefer = HtmlTree.P(contents.getContent("doclet.help.search.refer", searchSpecLink));
344 htmlTree.add(searchIntro);
345 htmlTree.add(searchExamples);
346 htmlTree.add(searchRefer);
347 ul.add(HtmlTree.LI(HtmlStyle.blockList, htmlTree));
348
349 Content divContent = HtmlTree.DIV(HtmlStyle.contentContainer, ul);
350 divContent.add(new HtmlTree(HtmlTag.HR));
351 Content footnote = HtmlTree.SPAN(HtmlStyle.emphasizedPhrase,
352 contents.getContent("doclet.help.footnote"));
353 divContent.add(footnote);
354 contentTree.add(divContent);
355 }
356 }