|
1 /* |
|
2 * Copyright (c) 2013, 2016, 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 java.io.*; |
|
29 import java.util.List; |
|
30 import java.util.Set; |
|
31 |
|
32 import javax.lang.model.element.ModuleElement; |
|
33 import javax.lang.model.element.PackageElement; |
|
34 |
|
35 import com.sun.source.doctree.DocTree; |
|
36 |
|
37 import jdk.javadoc.internal.doclets.formats.html.markup.HtmlConstants; |
|
38 import jdk.javadoc.internal.doclets.formats.html.markup.HtmlStyle; |
|
39 import jdk.javadoc.internal.doclets.formats.html.markup.HtmlTag; |
|
40 import jdk.javadoc.internal.doclets.formats.html.markup.HtmlTree; |
|
41 import jdk.javadoc.internal.doclets.formats.html.markup.RawHtml; |
|
42 import jdk.javadoc.internal.doclets.toolkit.Content; |
|
43 import jdk.javadoc.internal.doclets.toolkit.ModuleSummaryWriter; |
|
44 import jdk.javadoc.internal.doclets.toolkit.util.CommentHelper; |
|
45 import jdk.javadoc.internal.doclets.toolkit.util.DocPaths; |
|
46 |
|
47 /** |
|
48 * Class to generate file for each module contents in the right-hand |
|
49 * frame. This will list all the packages and Class Kinds in the module. A click on any |
|
50 * class-kind will update the frame with the clicked class-kind page. A click on any |
|
51 * package will update the frame with the clicked module package page. |
|
52 * |
|
53 * <p><b>This is NOT part of any supported API. |
|
54 * If you write code that depends on this, you do so at your own risk. |
|
55 * This code and its internal interfaces are subject to change or |
|
56 * deletion without notice.</b> |
|
57 * |
|
58 * @author Bhavesh Patel |
|
59 */ |
|
60 public class ModuleWriterImpl extends HtmlDocletWriter implements ModuleSummaryWriter { |
|
61 |
|
62 /** |
|
63 * The prev module name in the alpha-order list. |
|
64 */ |
|
65 protected ModuleElement prevModule; |
|
66 |
|
67 /** |
|
68 * The next module name in the alpha-order list. |
|
69 */ |
|
70 protected ModuleElement nextModule; |
|
71 |
|
72 /** |
|
73 * The module being documented. |
|
74 */ |
|
75 protected ModuleElement mdle; |
|
76 |
|
77 /** |
|
78 * The HTML tree for main tag. |
|
79 */ |
|
80 protected HtmlTree mainTree = HtmlTree.MAIN(); |
|
81 |
|
82 /** |
|
83 * Constructor to construct ModuleWriter object and to generate |
|
84 * "moduleName-summary.html" file. |
|
85 * |
|
86 * @param configuration the configuration of the doclet. |
|
87 * @param module Module under consideration. |
|
88 * @param prevModule Previous module in the sorted array. |
|
89 * @param nextModule Next module in the sorted array. |
|
90 */ |
|
91 public ModuleWriterImpl(ConfigurationImpl configuration, |
|
92 ModuleElement mdle, ModuleElement prevModule, ModuleElement nextModule) |
|
93 throws IOException { |
|
94 super(configuration, DocPaths.moduleSummary(mdle)); |
|
95 this.prevModule = prevModule; |
|
96 this.nextModule = nextModule; |
|
97 this.mdle = mdle; |
|
98 } |
|
99 |
|
100 /** |
|
101 * {@inheritDoc} |
|
102 */ |
|
103 public Content getModuleHeader(String heading) { |
|
104 HtmlTree bodyTree = getBody(true, getWindowTitle(mdle.getQualifiedName().toString())); |
|
105 HtmlTree htmlTree = (configuration.allowTag(HtmlTag.HEADER)) |
|
106 ? HtmlTree.HEADER() |
|
107 : bodyTree; |
|
108 addTop(htmlTree); |
|
109 addNavLinks(true, htmlTree); |
|
110 if (configuration.allowTag(HtmlTag.HEADER)) { |
|
111 bodyTree.addContent(htmlTree); |
|
112 } |
|
113 HtmlTree div = new HtmlTree(HtmlTag.DIV); |
|
114 div.addStyle(HtmlStyle.header); |
|
115 Content tHeading = HtmlTree.HEADING(HtmlConstants.TITLE_HEADING, true, |
|
116 HtmlStyle.title, moduleLabel); |
|
117 tHeading.addContent(getSpace()); |
|
118 Content moduleHead = new RawHtml(heading); |
|
119 tHeading.addContent(moduleHead); |
|
120 div.addContent(tHeading); |
|
121 if (configuration.allowTag(HtmlTag.MAIN)) { |
|
122 mainTree.addContent(div); |
|
123 } else { |
|
124 bodyTree.addContent(div); |
|
125 } |
|
126 return bodyTree; |
|
127 } |
|
128 |
|
129 /** |
|
130 * {@inheritDoc} |
|
131 */ |
|
132 public Content getContentHeader() { |
|
133 HtmlTree div = new HtmlTree(HtmlTag.DIV); |
|
134 div.addStyle(HtmlStyle.contentContainer); |
|
135 return div; |
|
136 } |
|
137 |
|
138 /** |
|
139 * {@inheritDoc} |
|
140 */ |
|
141 public Content getSummaryHeader() { |
|
142 HtmlTree li = new HtmlTree(HtmlTag.LI); |
|
143 li.addStyle(HtmlStyle.blockList); |
|
144 return li; |
|
145 } |
|
146 |
|
147 /** |
|
148 * {@inheritDoc} |
|
149 */ |
|
150 public Content getSummaryTree(Content summaryContentTree) { |
|
151 HtmlTree ul = HtmlTree.UL(HtmlStyle.blockList, summaryContentTree); |
|
152 return ul; |
|
153 } |
|
154 |
|
155 /** |
|
156 * {@inheritDoc} |
|
157 */ |
|
158 public void addPackagesSummary(Set<PackageElement> packages, String text, |
|
159 String tableSummary, Content summaryContentTree) { |
|
160 Content table = (configuration.isOutputHtml5()) |
|
161 ? HtmlTree.TABLE(HtmlStyle.overviewSummary, getTableCaption(new RawHtml(text))) |
|
162 : HtmlTree.TABLE(HtmlStyle.overviewSummary, tableSummary, getTableCaption(new RawHtml(text))); |
|
163 table.addContent(getSummaryTableHeader(packageTableHeader, "col")); |
|
164 Content tbody = new HtmlTree(HtmlTag.TBODY); |
|
165 addPackagesList(packages, tbody); |
|
166 table.addContent(tbody); |
|
167 summaryContentTree.addContent(table); |
|
168 } |
|
169 |
|
170 /** |
|
171 * Adds list of packages in the package summary table. Generate link to each package. |
|
172 * |
|
173 * @param packages Packages to which link is to be generated |
|
174 * @param tbody the documentation tree to which the list will be added |
|
175 */ |
|
176 protected void addPackagesList(Set<PackageElement> packages, Content tbody) { |
|
177 boolean altColor = true; |
|
178 for (PackageElement pkg : packages) { |
|
179 if (pkg != null && !pkg.isUnnamed()) { |
|
180 if (!(configuration.nodeprecated && utils.isDeprecated(pkg))) { |
|
181 Content packageLinkContent = getPackageLink(pkg, getPackageName(pkg)); |
|
182 Content tdPackage = HtmlTree.TD(HtmlStyle.colFirst, packageLinkContent); |
|
183 HtmlTree tdSummary = new HtmlTree(HtmlTag.TD); |
|
184 tdSummary.addStyle(HtmlStyle.colLast); |
|
185 addSummaryComment(pkg, tdSummary); |
|
186 HtmlTree tr = HtmlTree.TR(tdPackage); |
|
187 tr.addContent(tdSummary); |
|
188 tr.addStyle(altColor ? HtmlStyle.altColor : HtmlStyle.rowColor); |
|
189 tbody.addContent(tr); |
|
190 } |
|
191 } |
|
192 altColor = !altColor; |
|
193 } |
|
194 } |
|
195 |
|
196 /** |
|
197 * {@inheritDoc} |
|
198 */ |
|
199 public void addModuleContent(Content contentTree, Content moduleContentTree) { |
|
200 if (configuration.allowTag(HtmlTag.MAIN)) { |
|
201 mainTree.addContent(moduleContentTree); |
|
202 contentTree.addContent(mainTree); |
|
203 } else { |
|
204 contentTree.addContent(moduleContentTree); |
|
205 } |
|
206 } |
|
207 |
|
208 /** |
|
209 * {@inheritDoc} |
|
210 */ |
|
211 public void addModuleFooter(Content contentTree) { |
|
212 Content htmlTree = (configuration.allowTag(HtmlTag.FOOTER)) |
|
213 ? HtmlTree.FOOTER() |
|
214 : contentTree; |
|
215 addNavLinks(false, htmlTree); |
|
216 addBottom(htmlTree); |
|
217 if (configuration.allowTag(HtmlTag.FOOTER)) { |
|
218 contentTree.addContent(htmlTree); |
|
219 } |
|
220 } |
|
221 |
|
222 /** |
|
223 * {@inheritDoc} |
|
224 */ |
|
225 public void printDocument(Content contentTree) throws IOException { |
|
226 printHtmlDocument(configuration.metakeywords.getMetaKeywordsForModule(mdle), |
|
227 true, contentTree); |
|
228 } |
|
229 |
|
230 /** |
|
231 * Add the module package deprecation information to the documentation tree. |
|
232 * |
|
233 * @param li the content tree to which the deprecation information will be added |
|
234 * @param pkg the PackageDoc that is added |
|
235 */ |
|
236 public void addPackageDeprecationInfo(Content li, PackageElement pkg) { |
|
237 List<? extends DocTree> deprs; |
|
238 if (utils.isDeprecated(pkg)) { |
|
239 deprs = utils.getDeprecatedTrees(pkg); |
|
240 HtmlTree deprDiv = new HtmlTree(HtmlTag.DIV); |
|
241 deprDiv.addStyle(HtmlStyle.deprecatedContent); |
|
242 Content deprPhrase = HtmlTree.SPAN(HtmlStyle.deprecatedLabel, deprecatedPhrase); |
|
243 deprDiv.addContent(deprPhrase); |
|
244 if (!deprs.isEmpty()) { |
|
245 CommentHelper ch = utils.getCommentHelper(pkg); |
|
246 List<? extends DocTree> commentTags = ch.getDescription(configuration, deprs.get(0)); |
|
247 if (!commentTags.isEmpty()) { |
|
248 addInlineDeprecatedComment(pkg, deprs.get(0), deprDiv); |
|
249 } |
|
250 } |
|
251 li.addContent(deprDiv); |
|
252 } |
|
253 } |
|
254 |
|
255 /** |
|
256 * Get "PREV MODULE" link in the navigation bar. |
|
257 * |
|
258 * @return a content tree for the previous link |
|
259 */ |
|
260 public Content getNavLinkPrevious() { |
|
261 Content li; |
|
262 if (prevModule == null) { |
|
263 li = HtmlTree.LI(prevmoduleLabel); |
|
264 } else { |
|
265 li = HtmlTree.LI(getHyperLink(pathToRoot.resolve(DocPaths.moduleSummary( |
|
266 prevModule)), prevmoduleLabel, "", "")); |
|
267 } |
|
268 return li; |
|
269 } |
|
270 |
|
271 /** |
|
272 * Get "NEXT MODULE" link in the navigation bar. |
|
273 * |
|
274 * @return a content tree for the next link |
|
275 */ |
|
276 public Content getNavLinkNext() { |
|
277 Content li; |
|
278 if (nextModule == null) { |
|
279 li = HtmlTree.LI(nextmoduleLabel); |
|
280 } else { |
|
281 li = HtmlTree.LI(getHyperLink(pathToRoot.resolve(DocPaths.moduleSummary( |
|
282 nextModule)), nextmoduleLabel, "", "")); |
|
283 } |
|
284 return li; |
|
285 } |
|
286 } |