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