Wed, 01 Dec 2010 11:02:38 -0800
6851834: Javadoc doclet needs a structured approach to generate the output HTML.
Reviewed-by: jjg
1 /*
2 * Copyright (c) 2003, 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 */
26 package com.sun.tools.doclets.internal.toolkit.builders;
28 import java.io.*;
29 import com.sun.javadoc.*;
30 import com.sun.tools.doclets.internal.toolkit.util.*;
31 import com.sun.tools.doclets.internal.toolkit.*;
33 /**
34 * Builds the summary for a given package.
35 *
36 * This code is not part of an API.
37 * It is implementation that is subject to change.
38 * Do not use it as an API
39 *
40 * @author Jamie Ho
41 * @author Bhavesh Patel (Modified)
42 * @since 1.5
43 */
44 public class PackageSummaryBuilder extends AbstractBuilder {
45 /**
46 * The root element of the package summary XML is {@value}.
47 */
48 public static final String ROOT = "PackageDoc";
50 /**
51 * The package being documented.
52 */
53 private PackageDoc packageDoc;
55 /**
56 * The doclet specific writer that will output the result.
57 */
58 private PackageSummaryWriter packageWriter;
60 /**
61 * The content that will be added to the package summary documentation tree.
62 */
63 private Content contentTree;
65 private PackageSummaryBuilder(Configuration configuration) {
66 super(configuration);
67 }
69 /**
70 * Construct a new PackageSummaryBuilder.
71 * @param configuration the current configuration of the doclet.
72 * @param pkg the package being documented.
73 * @param packageWriter the doclet specific writer that will output the
74 * result.
75 *
76 * @return an instance of a PackageSummaryBuilder.
77 */
78 public static PackageSummaryBuilder getInstance(
79 Configuration configuration,
80 PackageDoc pkg,
81 PackageSummaryWriter packageWriter) {
82 PackageSummaryBuilder builder =
83 new PackageSummaryBuilder(configuration);
84 builder.packageDoc = pkg;
85 builder.packageWriter = packageWriter;
86 return builder;
87 }
89 /**
90 * Build the package summary.
91 */
92 public void build() throws IOException {
93 if (packageWriter == null) {
94 //Doclet does not support this output.
95 return;
96 }
97 build(LayoutParser.getInstance(configuration).parseXML(ROOT), contentTree);
98 }
100 /**
101 * {@inheritDoc}
102 */
103 public String getName() {
104 return ROOT;
105 }
107 /**
108 * Build the package documentation.
109 *
110 * @param node the XML element that specifies which components to document
111 * @param contentTree the content tree to which the documentation will be added
112 */
113 public void buildPackageDoc(XMLNode node, Content contentTree) throws Exception {
114 contentTree = packageWriter.getPackageHeader(
115 Util.getPackageName(packageDoc));
116 buildChildren(node, contentTree);
117 packageWriter.addPackageFooter(contentTree);
118 packageWriter.printDocument(contentTree);
119 packageWriter.close();
120 Util.copyDocFiles(
121 configuration,
122 Util.getPackageSourcePath(configuration, packageDoc),
123 DirectoryManager.getDirectoryPath(packageDoc)
124 + File.separator
125 + DocletConstants.DOC_FILES_DIR_NAME,
126 true);
127 }
129 /**
130 * Build the content for the package doc.
131 *
132 * @param node the XML element that specifies which components to document
133 * @param contentTree the content tree to which the package contents
134 * will be added
135 */
136 public void buildContent(XMLNode node, Content contentTree) {
137 Content packageContentTree = packageWriter.getContentHeader();
138 buildChildren(node, packageContentTree);
139 contentTree.addContent(packageContentTree);
140 }
142 /**
143 * Build the package summary.
144 *
145 * @param node the XML element that specifies which components to document
146 * @param packageContentTree the package content tree to which the summaries will
147 * be added
148 */
149 public void buildSummary(XMLNode node, Content packageContentTree) {
150 Content summaryContentTree = packageWriter.getSummaryHeader();
151 buildChildren(node, summaryContentTree);
152 packageContentTree.addContent(summaryContentTree);
153 }
155 /**
156 * Build the summary for the interfaces in this package.
157 *
158 * @param node the XML element that specifies which components to document
159 * @param summaryContentTree the summary tree to which the interface summary
160 * will be added
161 */
162 public void buildInterfaceSummary(XMLNode node, Content summaryContentTree) {
163 String interfaceTableSummary =
164 configuration.getText("doclet.Member_Table_Summary",
165 configuration.getText("doclet.Interface_Summary"),
166 configuration.getText("doclet.interfaces"));
167 String[] interfaceTableHeader = new String[] {
168 configuration.getText("doclet.Interface"),
169 configuration.getText("doclet.Description")
170 };
171 ClassDoc[] interfaces =
172 packageDoc.isIncluded()
173 ? packageDoc.interfaces()
174 : configuration.classDocCatalog.interfaces(
175 Util.getPackageName(packageDoc));
176 if (interfaces.length > 0) {
177 packageWriter.addClassesSummary(
178 interfaces,
179 configuration.getText("doclet.Interface_Summary"),
180 interfaceTableSummary, interfaceTableHeader, summaryContentTree);
181 }
182 }
184 /**
185 * Build the summary for the classes in this package.
186 *
187 * @param node the XML element that specifies which components to document
188 * @param summaryContentTree the summary tree to which the class summary will
189 * be added
190 */
191 public void buildClassSummary(XMLNode node, Content summaryContentTree) {
192 String classTableSummary =
193 configuration.getText("doclet.Member_Table_Summary",
194 configuration.getText("doclet.Class_Summary"),
195 configuration.getText("doclet.classes"));
196 String[] classTableHeader = new String[] {
197 configuration.getText("doclet.Class"),
198 configuration.getText("doclet.Description")
199 };
200 ClassDoc[] classes =
201 packageDoc.isIncluded()
202 ? packageDoc.ordinaryClasses()
203 : configuration.classDocCatalog.ordinaryClasses(
204 Util.getPackageName(packageDoc));
205 if (classes.length > 0) {
206 packageWriter.addClassesSummary(
207 classes,
208 configuration.getText("doclet.Class_Summary"),
209 classTableSummary, classTableHeader, summaryContentTree);
210 }
211 }
213 /**
214 * Build the summary for the enums in this package.
215 *
216 * @param node the XML element that specifies which components to document
217 * @param summaryContentTree the summary tree to which the enum summary will
218 * be added
219 */
220 public void buildEnumSummary(XMLNode node, Content summaryContentTree) {
221 String enumTableSummary =
222 configuration.getText("doclet.Member_Table_Summary",
223 configuration.getText("doclet.Enum_Summary"),
224 configuration.getText("doclet.enums"));
225 String[] enumTableHeader = new String[] {
226 configuration.getText("doclet.Enum"),
227 configuration.getText("doclet.Description")
228 };
229 ClassDoc[] enums =
230 packageDoc.isIncluded()
231 ? packageDoc.enums()
232 : configuration.classDocCatalog.enums(
233 Util.getPackageName(packageDoc));
234 if (enums.length > 0) {
235 packageWriter.addClassesSummary(
236 enums,
237 configuration.getText("doclet.Enum_Summary"),
238 enumTableSummary, enumTableHeader, summaryContentTree);
239 }
240 }
242 /**
243 * Build the summary for the exceptions in this package.
244 *
245 * @param node the XML element that specifies which components to document
246 * @param summaryContentTree the summary tree to which the exception summary will
247 * be added
248 */
249 public void buildExceptionSummary(XMLNode node, Content summaryContentTree) {
250 String exceptionTableSummary =
251 configuration.getText("doclet.Member_Table_Summary",
252 configuration.getText("doclet.Exception_Summary"),
253 configuration.getText("doclet.exceptions"));
254 String[] exceptionTableHeader = new String[] {
255 configuration.getText("doclet.Exception"),
256 configuration.getText("doclet.Description")
257 };
258 ClassDoc[] exceptions =
259 packageDoc.isIncluded()
260 ? packageDoc.exceptions()
261 : configuration.classDocCatalog.exceptions(
262 Util.getPackageName(packageDoc));
263 if (exceptions.length > 0) {
264 packageWriter.addClassesSummary(
265 exceptions,
266 configuration.getText("doclet.Exception_Summary"),
267 exceptionTableSummary, exceptionTableHeader, summaryContentTree);
268 }
269 }
271 /**
272 * Build the summary for the errors in this package.
273 *
274 * @param node the XML element that specifies which components to document
275 * @param summaryContentTree the summary tree to which the error summary will
276 * be added
277 */
278 public void buildErrorSummary(XMLNode node, Content summaryContentTree) {
279 String errorTableSummary =
280 configuration.getText("doclet.Member_Table_Summary",
281 configuration.getText("doclet.Error_Summary"),
282 configuration.getText("doclet.errors"));
283 String[] errorTableHeader = new String[] {
284 configuration.getText("doclet.Error"),
285 configuration.getText("doclet.Description")
286 };
287 ClassDoc[] errors =
288 packageDoc.isIncluded()
289 ? packageDoc.errors()
290 : configuration.classDocCatalog.errors(
291 Util.getPackageName(packageDoc));
292 if (errors.length > 0) {
293 packageWriter.addClassesSummary(
294 errors,
295 configuration.getText("doclet.Error_Summary"),
296 errorTableSummary, errorTableHeader, summaryContentTree);
297 }
298 }
300 /**
301 * Build the summary for the annotation type in this package.
302 *
303 * @param node the XML element that specifies which components to document
304 * @param summaryContentTree the summary tree to which the annotation type
305 * summary will be added
306 */
307 public void buildAnnotationTypeSummary(XMLNode node, Content summaryContentTree) {
308 String annotationtypeTableSummary =
309 configuration.getText("doclet.Member_Table_Summary",
310 configuration.getText("doclet.Annotation_Types_Summary"),
311 configuration.getText("doclet.annotationtypes"));
312 String[] annotationtypeTableHeader = new String[] {
313 configuration.getText("doclet.AnnotationType"),
314 configuration.getText("doclet.Description")
315 };
316 ClassDoc[] annotationTypes =
317 packageDoc.isIncluded()
318 ? packageDoc.annotationTypes()
319 : configuration.classDocCatalog.annotationTypes(
320 Util.getPackageName(packageDoc));
321 if (annotationTypes.length > 0) {
322 packageWriter.addClassesSummary(
323 annotationTypes,
324 configuration.getText("doclet.Annotation_Types_Summary"),
325 annotationtypeTableSummary, annotationtypeTableHeader,
326 summaryContentTree);
327 }
328 }
330 /**
331 * Build the description of the summary.
332 *
333 * @param node the XML element that specifies which components to document
334 * @param packageContentTree the tree to which the package description will
335 * be added
336 */
337 public void buildPackageDescription(XMLNode node, Content packageContentTree) {
338 if (configuration.nocomment) {
339 return;
340 }
341 packageWriter.addPackageDescription(packageContentTree);
342 }
344 /**
345 * Build the tags of the summary.
346 *
347 * @param node the XML element that specifies which components to document
348 * @param packageContentTree the tree to which the package tags will be added
349 */
350 public void buildPackageTags(XMLNode node, Content packageContentTree) {
351 if (configuration.nocomment) {
352 return;
353 }
354 packageWriter.addPackageTags(packageContentTree);
355 }
356 }