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