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