1 /*
2 * Copyright (c) 2003, 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.toolkit.builders;
27
28 import java.io.*;
29
30 import javax.lang.model.element.PackageElement;
31 import javax.lang.model.element.TypeElement;
32
33 import jdk.javadoc.internal.doclets.toolkit.ClassWriter;
34 import jdk.javadoc.internal.doclets.toolkit.Content;
35 import jdk.javadoc.internal.doclets.toolkit.util.Utils;
36
37 /**
38 * Builds the summary for a given class.
39 *
40 * <p><b>This is NOT part of any supported API.
41 * If you write code that depends on this, you do so at your own risk.
42 * This code and its internal interfaces are subject to change or
43 * deletion without notice.</b>
44 *
45 * @author Jamie Ho
46 * @author Bhavesh Patel (Modified)
47 * @since 1.5
48 */
49 public class ClassBuilder extends AbstractBuilder {
50
51 /**
52 * The root element of the class XML is {@value}.
53 */
54 public static final String ROOT = "ClassDoc";
55
56 /**
57 * The class being documented.
58 */
59 private final TypeElement typeElement;
60
61 /**
62 * The doclet specific writer.
63 */
64 private final ClassWriter writer;
65
66 /**
67 * Keep track of whether or not this typeElement is an interface.
68 */
69 private final boolean isInterface;
70
71 /**
72 * Keep track of whether or not this typeElement is an enum.
73 */
74 private final boolean isEnum;
75
76 /**
77 * The content tree for the class documentation.
78 */
79 private Content contentTree;
80
81 private final Utils utils;
82
83 /**
84 * Construct a new ClassBuilder.
85 *
86 * @param context the build context
87 * @param typeElement the class being documented.
88 * @param writer the doclet specific writer.
89 */
90 private ClassBuilder(Context context, TypeElement typeElement, ClassWriter writer) {
91 super(context);
92 this.typeElement = typeElement;
93 this.writer = writer;
94 this.utils = configuration.utils;
95 if (utils.isInterface(typeElement)) {
96 isInterface = true;
97 isEnum = false;
98 } else if (utils.isEnum(typeElement)) {
99 isInterface = false;
100 isEnum = true;
101 utils.setEnumDocumentation(typeElement);
102 } else {
103 isInterface = false;
104 isEnum = false;
105 }
106 }
107
108 /**
109 * Construct a new ClassBuilder.
110 *
111 * @param context the build context
112 * @param typeElement the class being documented.
113 * @param writer the doclet specific writer.
114 */
115 public static ClassBuilder getInstance(Context context,
116 TypeElement typeElement, ClassWriter writer) {
117 return new ClassBuilder(context, typeElement, writer);
118 }
119
120 /**
121 * {@inheritDoc}
122 */
123 public void build() throws IOException {
124 build(layoutParser.parseXML(ROOT), contentTree);
125 }
126
127 /**
128 * {@inheritDoc}
129 */
130 public String getName() {
131 return ROOT;
132 }
133
134 /**
135 * Handles the {@literal <TypeElement>} tag.
136 *
137 * @param node the XML element that specifies which components to document
138 * @param contentTree the content tree to which the documentation will be added
139 */
140 public void buildClassDoc(XMLNode node, Content contentTree) throws Exception {
141 String key;
142 if (isInterface) {
143 key = "doclet.Interface";
144 } else if (isEnum) {
145 key = "doclet.Enum";
146 } else {
147 key = "doclet.Class";
148 }
149 contentTree = writer.getHeader(configuration.getText(key) + " " +
150 utils.getSimpleName(typeElement));
151 Content classContentTree = writer.getClassContentHeader();
152 buildChildren(node, classContentTree);
153 writer.addClassContentTree(contentTree, classContentTree);
154 writer.addFooter(contentTree);
155 writer.printDocument(contentTree);
156 writer.close();
157 copyDocFiles();
158 }
159
160 /**
161 * Build the class tree documentation.
162 *
163 * @param node the XML element that specifies which components to document
164 * @param classContentTree the content tree to which the documentation will be added
165 */
166 public void buildClassTree(XMLNode node, Content classContentTree) {
167 writer.addClassTree(classContentTree);
168 }
169
170 /**
171 * Build the class information tree documentation.
172 *
173 * @param node the XML element that specifies which components to document
174 * @param classContentTree the content tree to which the documentation will be added
175 */
176 public void buildClassInfo(XMLNode node, Content classContentTree) {
177 Content classInfoTree = writer.getClassInfoTreeHeader();
178 buildChildren(node, classInfoTree);
179 classContentTree.addContent(writer.getClassInfo(classInfoTree));
180 }
181
182 /**
183 * Build the typeparameters of this class.
184 *
185 * @param node the XML element that specifies which components to document
186 * @param classInfoTree the content tree to which the documentation will be added
187 */
188 public void buildTypeParamInfo(XMLNode node, Content classInfoTree) {
189 writer.addTypeParamInfo(classInfoTree);
190 }
191
192 /**
193 * If this is an interface, list all super interfaces.
194 *
195 * @param node the XML element that specifies which components to document
196 * @param classInfoTree the content tree to which the documentation will be added
197 */
198 public void buildSuperInterfacesInfo(XMLNode node, Content classInfoTree) {
199 writer.addSuperInterfacesInfo(classInfoTree);
200 }
201
202 /**
203 * If this is a class, list all interfaces implemented by this class.
204 *
205 * @param node the XML element that specifies which components to document
206 * @param classInfoTree the content tree to which the documentation will be added
207 */
208 public void buildImplementedInterfacesInfo(XMLNode node, Content classInfoTree) {
209 writer.addImplementedInterfacesInfo(classInfoTree);
210 }
211
212 /**
213 * List all the classes extend this one.
214 *
215 * @param node the XML element that specifies which components to document
216 * @param classInfoTree the content tree to which the documentation will be added
217 */
218 public void buildSubClassInfo(XMLNode node, Content classInfoTree) {
219 writer.addSubClassInfo(classInfoTree);
220 }
221
222 /**
223 * List all the interfaces that extend this one.
224 *
225 * @param node the XML element that specifies which components to document
226 * @param classInfoTree the content tree to which the documentation will be added
227 */
228 public void buildSubInterfacesInfo(XMLNode node, Content classInfoTree) {
229 writer.addSubInterfacesInfo(classInfoTree);
230 }
231
232 /**
233 * If this is an interface, list all classes that implement this interface.
234 *
235 * @param node the XML element that specifies which components to document
236 * @param classInfoTree the content tree to which the documentation will be added
237 */
238 public void buildInterfaceUsageInfo(XMLNode node, Content classInfoTree) {
239 writer.addInterfaceUsageInfo(classInfoTree);
240 }
241
242 /**
243 * If this is an functional interface, display appropriate message.
244 *
245 * @param node the XML element that specifies which components to document
246 * @param classInfoTree the content tree to which the documentation will be added
247 */
248 public void buildFunctionalInterfaceInfo(XMLNode node, Content classInfoTree) {
249 writer.addFunctionalInterfaceInfo(classInfoTree);
250 }
251
252 /**
253 * If this class is deprecated, build the appropriate information.
254 *
255 * @param node the XML element that specifies which components to document
256 * @param classInfoTree the content tree to which the documentation will be added
257 */
258 public void buildDeprecationInfo (XMLNode node, Content classInfoTree) {
259 writer.addClassDeprecationInfo(classInfoTree);
260 }
261
262 /**
263 * If this is an inner class or interface, list the enclosing class or interface.
264 *
265 * @param node the XML element that specifies which components to document
266 * @param classInfoTree the content tree to which the documentation will be added
267 */
268 public void buildNestedClassInfo (XMLNode node, Content classInfoTree) {
269 writer.addNestedClassInfo(classInfoTree);
270 }
271
272 /**
273 * Copy the doc files for the current ClassDoc if necessary.
274 */
275 private void copyDocFiles() {
276 PackageElement containingPackage = utils.containingPackage(typeElement);
277 if((configuration.packages == null ||
278 !configuration.packages.contains(containingPackage)) &&
279 !containingPackagesSeen.contains(containingPackage)) {
280 //Only copy doc files dir if the containing package is not
281 //documented AND if we have not documented a class from the same
282 //package already. Otherwise, we are making duplicate copies.
283 utils.copyDocFiles(containingPackage);
284 containingPackagesSeen.add(containingPackage);
285 }
286 }
287
288 /**
289 * Build the signature of the current class.
290 *
291 * @param node the XML element that specifies which components to document
292 * @param classInfoTree the content tree to which the documentation will be added
293 */
294 public void buildClassSignature(XMLNode node, Content classInfoTree) {
295 writer.addClassSignature(utils.modifiersToString(typeElement, true), classInfoTree);
296 }
297
298 /**
299 * Build the class description.
300 *
301 * @param node the XML element that specifies which components to document
302 * @param classInfoTree the content tree to which the documentation will be added
303 */
304 public void buildClassDescription(XMLNode node, Content classInfoTree) {
305 writer.addClassDescription(classInfoTree);
306 }
307
308 /**
309 * Build the tag information for the current class.
310 *
311 * @param node the XML element that specifies which components to document
312 * @param classInfoTree the content tree to which the documentation will be added
313 */
314 public void buildClassTagInfo(XMLNode node, Content classInfoTree) {
315 writer.addClassTagInfo(classInfoTree);
316 }
317
318 /**
319 * Build the member summary contents of the page.
320 *
321 * @param node the XML element that specifies which components to document
322 * @param classContentTree the content tree to which the documentation will be added
323 */
324 public void buildMemberSummary(XMLNode node, Content classContentTree) throws Exception {
325 Content memberSummaryTree = writer.getMemberTreeHeader();
326 configuration.getBuilderFactory().
327 getMemberSummaryBuilder(writer).buildChildren(node, memberSummaryTree);
328 classContentTree.addContent(writer.getMemberSummaryTree(memberSummaryTree));
329 }
330
331 /**
332 * Build the member details contents of the page.
333 *
334 * @param node the XML element that specifies which components to document
335 * @param classContentTree the content tree to which the documentation will be added
336 */
337 public void buildMemberDetails(XMLNode node, Content classContentTree) {
338 Content memberDetailsTree = writer.getMemberTreeHeader();
339 buildChildren(node, memberDetailsTree);
340 classContentTree.addContent(writer.getMemberDetailsTree(memberDetailsTree));
341 }
342
343 /**
344 * Build the enum constants documentation.
345 *
346 * @param node the XML element that specifies which components to document
347 * @param memberDetailsTree the content tree to which the documentation will be added
348 */
349 public void buildEnumConstantsDetails(XMLNode node,
350 Content memberDetailsTree) throws Exception {
351 configuration.getBuilderFactory().
352 getEnumConstantsBuilder(writer).buildChildren(node, memberDetailsTree);
353 }
354
355 /**
356 * Build the field documentation.
357 *
358 * @param node the XML element that specifies which components to document
359 * @param memberDetailsTree the content tree to which the documentation will be added
360 */
361 public void buildFieldDetails(XMLNode node,
362 Content memberDetailsTree) throws Exception {
363 configuration.getBuilderFactory().
364 getFieldBuilder(writer).buildChildren(node, memberDetailsTree);
365 }
366
367 /**
368 * Build the property documentation.
369 *
370 * @param elements the XML elements that specify how a field is documented.
371 */
372 public void buildPropertyDetails(XMLNode node,
373 Content memberDetailsTree) throws Exception {
374 configuration.getBuilderFactory().
375 getPropertyBuilder(writer).buildChildren(node, memberDetailsTree);
376 }
377
378 /**
379 * Build the constructor documentation.
380 *
381 * @param node the XML element that specifies which components to document
382 * @param memberDetailsTree the content tree to which the documentation will be added
383 */
384 public void buildConstructorDetails(XMLNode node,
385 Content memberDetailsTree) throws Exception {
386 configuration.getBuilderFactory().
387 getConstructorBuilder(writer).buildChildren(node, memberDetailsTree);
388 }
389
390 /**
391 * Build the method documentation.
392 *
393 * @param node the XML element that specifies which components to document
394 * @param memberDetailsTree the content tree to which the documentation will be added
395 */
396 public void buildMethodDetails(XMLNode node,
397 Content memberDetailsTree) throws Exception {
398 configuration.getBuilderFactory().
399 getMethodBuilder(writer).buildChildren(node, memberDetailsTree);
400 }
401 }