1 /* 2 * Copyright (c) 2003, 2015, 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 com.sun.tools.doclets.internal.toolkit.builders; 27 28 import java.io.*; 29 30 import com.sun.javadoc.*; 31 import com.sun.tools.doclets.internal.toolkit.*; 32 33 /** 34 * Builds the summary for a given class. 35 * 36 * <p><b>This is NOT part of any supported API. 37 * If you write code that depends on this, you do so at your own risk. 38 * This code and its internal interfaces are subject to change or 39 * deletion without notice.</b> 40 * 41 * @author Jamie Ho 42 * @author Bhavesh Patel (Modified) 43 * @since 1.5 44 */ 45 public class ClassBuilder extends AbstractBuilder { 46 47 /** 48 * The root element of the class XML is {@value}. 49 */ 50 public static final String ROOT = "ClassDoc"; 51 52 /** 53 * The class being documented. 54 */ 55 private final ClassDoc classDoc; 56 57 /** 58 * The doclet specific writer. 59 */ 60 private final ClassWriter writer; 61 62 /** 63 * Keep track of whether or not this classdoc is an interface. 64 */ 65 private final boolean isInterface; 66 67 /** 68 * Keep track of whether or not this classdoc is an enum. 69 */ 70 private final boolean isEnum; 71 72 /** 73 * The content tree for the class documentation. 74 */ 75 private Content contentTree; 76 77 /** 78 * Construct a new ClassBuilder. 79 * 80 * @param context the build context 81 * @param classDoc the class being documented. 82 * @param writer the doclet specific writer. 83 */ 84 private ClassBuilder(Context context, 85 ClassDoc classDoc, ClassWriter writer) { 86 super(context); 87 this.classDoc = classDoc; 88 this.writer = writer; 89 if (classDoc.isInterface()) { 90 isInterface = true; 91 isEnum = false; 92 } else if (classDoc.isEnum()) { 93 isInterface = false; 94 isEnum = true; 95 utils.setEnumDocumentation(configuration, classDoc); 96 } else { 97 isInterface = false; 98 isEnum = false; 99 } 100 } 101 102 /** 103 * Construct a new ClassBuilder. 104 * 105 * @param context the build context 106 * @param classDoc the class being documented. 107 * @param writer the doclet specific writer. 108 */ 109 public static ClassBuilder getInstance(Context context, 110 ClassDoc classDoc, ClassWriter writer) { 111 return new ClassBuilder(context, classDoc, writer); 112 } 113 114 /** 115 * {@inheritDoc} 116 */ 117 public void build() throws IOException { 118 build(layoutParser.parseXML(ROOT), contentTree); 119 } 120 121 /** 122 * {@inheritDoc} 123 */ 124 public String getName() { 125 return ROOT; 126 } 127 128 /** 129 * Handles the {@literal <ClassDoc>} tag. 130 * 131 * @param node the XML element that specifies which components to document 132 * @param contentTree the content tree to which the documentation will be added 133 */ 134 public void buildClassDoc(XMLNode node, Content contentTree) throws Exception { 135 String key; 136 if (isInterface) { 137 key = "doclet.Interface"; 138 } else if (isEnum) { 139 key = "doclet.Enum"; 140 } else { 141 key = "doclet.Class"; 142 } 143 contentTree = writer.getHeader(configuration.getText(key) + " " + 144 classDoc.name()); 145 Content classContentTree = writer.getClassContentHeader(); 146 buildChildren(node, classContentTree); 147 writer.addClassContentTree(contentTree, classContentTree); 148 writer.addFooter(contentTree); 149 writer.printDocument(contentTree); 150 writer.close(); 151 copyDocFiles(); 152 } 153 154 /** 155 * Build the class tree documentation. 156 * 157 * @param node the XML element that specifies which components to document 158 * @param classContentTree the content tree to which the documentation will be added 159 */ 160 public void buildClassTree(XMLNode node, Content classContentTree) { 161 writer.addClassTree(classContentTree); 162 } 163 164 /** 250 * @param classInfoTree the content tree to which the documentation will be added 251 */ 252 public void buildDeprecationInfo (XMLNode node, Content classInfoTree) { 253 writer.addClassDeprecationInfo(classInfoTree); 254 } 255 256 /** 257 * If this is an inner class or interface, list the enclosing class or interface. 258 * 259 * @param node the XML element that specifies which components to document 260 * @param classInfoTree the content tree to which the documentation will be added 261 */ 262 public void buildNestedClassInfo (XMLNode node, Content classInfoTree) { 263 writer.addNestedClassInfo(classInfoTree); 264 } 265 266 /** 267 * Copy the doc files for the current ClassDoc if necessary. 268 */ 269 private void copyDocFiles() { 270 PackageDoc containingPackage = classDoc.containingPackage(); 271 if((configuration.packages == null || 272 !configuration.packages.contains(containingPackage)) && 273 ! containingPackagesSeen.contains(containingPackage)){ 274 //Only copy doc files dir if the containing package is not 275 //documented AND if we have not documented a class from the same 276 //package already. Otherwise, we are making duplicate copies. 277 utils.copyDocFiles(configuration, containingPackage); 278 containingPackagesSeen.add(containingPackage); 279 } 280 } 281 282 /** 283 * Build the signature of the current class. 284 * 285 * @param node the XML element that specifies which components to document 286 * @param classInfoTree the content tree to which the documentation will be added 287 */ 288 public void buildClassSignature(XMLNode node, Content classInfoTree) { 289 StringBuilder modifiers = new StringBuilder(classDoc.modifiers()); 290 modifiers.append(modifiers.length() == 0 ? "" : " "); 291 if (isEnum) { 292 modifiers.append("enum "); 293 int index; 294 if ((index = modifiers.indexOf("abstract")) >= 0) { 295 modifiers.delete(index, index + "abstract".length()); 296 modifiers = new StringBuilder( 297 utils.replaceText(modifiers.toString(), " ", " ")); 298 } 299 if ((index = modifiers.indexOf("final")) >= 0) { 300 modifiers.delete(index, index + "final".length()); 301 modifiers = new StringBuilder( 302 utils.replaceText(modifiers.toString(), " ", " ")); 303 } 304 //} else if (classDoc.isAnnotationType()) { 305 //modifiers.append("@interface "); 306 } else if (! isInterface) { 307 modifiers.append("class "); 308 } 309 writer.addClassSignature(modifiers.toString(), classInfoTree); 310 } 311 312 /** 313 * Build the class description. 314 * 315 * @param node the XML element that specifies which components to document 316 * @param classInfoTree the content tree to which the documentation will be added 317 */ 318 public void buildClassDescription(XMLNode node, Content classInfoTree) { 319 writer.addClassDescription(classInfoTree); 320 } 321 322 /** 323 * Build the tag information for the current class. 324 * 325 * @param node the XML element that specifies which components to document 326 * @param classInfoTree the content tree to which the documentation will be added 327 */ 328 public void buildClassTagInfo(XMLNode node, Content classInfoTree) { 329 writer.addClassTagInfo(classInfoTree); 330 } | 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 /** 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 } |