1 /*
   2  * Copyright (c) 2003, 2019, 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.util.Iterator;
  29 import java.util.List;
  30 import java.util.Objects;
  31 import java.util.Set;
  32 import java.util.stream.Collectors;
  33 
  34 import javax.lang.model.element.Element;
  35 import javax.lang.model.element.ExecutableElement;
  36 import javax.lang.model.element.Name;
  37 import javax.lang.model.element.PackageElement;
  38 import javax.lang.model.element.TypeElement;
  39 import javax.lang.model.element.VariableElement;
  40 import javax.lang.model.type.TypeMirror;
  41 import javax.lang.model.util.Elements;
  42 
  43 import com.sun.source.tree.MethodTree;
  44 import com.sun.source.tree.Tree;
  45 import jdk.javadoc.internal.doclets.formats.html.markup.ContentBuilder;
  46 import jdk.javadoc.internal.doclets.toolkit.ClassWriter;
  47 import jdk.javadoc.internal.doclets.toolkit.CommentUtils;
  48 import jdk.javadoc.internal.doclets.toolkit.Content;
  49 import jdk.javadoc.internal.doclets.toolkit.DocFilesHandler;
  50 import jdk.javadoc.internal.doclets.toolkit.DocletException;
  51 import jdk.javadoc.internal.doclets.toolkit.util.DocFileIOException;
  52 import jdk.javadoc.internal.doclets.toolkit.util.Utils;
  53 
  54 /**
  55  * Builds the summary for a given class.
  56  *
  57  *  <p><b>This is NOT part of any supported API.
  58  *  If you write code that depends on this, you do so at your own risk.
  59  *  This code and its internal interfaces are subject to change or
  60  *  deletion without notice.</b>
  61  *
  62  * @author Jamie Ho
  63  * @author Bhavesh Patel (Modified)
  64  */
  65 public class ClassBuilder extends AbstractBuilder {
  66 
  67     /**
  68      * The class being documented.
  69      */
  70     private final TypeElement typeElement;
  71 
  72     /**
  73      * The doclet specific writer.
  74      */
  75     private final ClassWriter writer;
  76 
  77     /**
  78      * Keep track of whether or not this typeElement is an interface.
  79      */
  80     private final boolean isInterface;
  81 
  82     /**
  83      * Keep track of whether or not this typeElement is an enum.
  84      */
  85     private final boolean isEnum;
  86 
  87     /**
  88      * Keep track of whether or not this typeElement is an record.
  89      */
  90     private final boolean isRecord;
  91 
  92     /**
  93      * The content tree for the class documentation.
  94      */
  95     private Content contentTree;
  96 
  97     /**
  98      * Construct a new ClassBuilder.
  99      *
 100      * @param context  the build context
 101      * @param typeElement the class being documented.
 102      * @param writer the doclet specific writer.
 103      */
 104     private ClassBuilder(Context context, TypeElement typeElement, ClassWriter writer) {
 105         super(context);
 106         this.typeElement = typeElement;
 107         this.writer = writer;
 108         if (utils.isInterface(typeElement)) {
 109             isInterface = true;
 110             isEnum = false;
 111             isRecord = false;
 112         } else if (utils.isEnum(typeElement)) {
 113             isInterface = false;
 114             isEnum = true;
 115             isRecord = false;
 116             setEnumDocumentation(typeElement);
 117         } else if (utils.isRecord(typeElement)) {
 118             isInterface = false;
 119             isEnum = false;
 120             isRecord = true;
 121             setRecordDocumentation(typeElement);
 122         } else {
 123             isInterface = false;
 124             isEnum = false;
 125             isRecord = false;
 126         }
 127     }
 128 
 129     /**
 130      * Constructs a new ClassBuilder.
 131      *
 132      * @param context  the build context
 133      * @param typeElement the class being documented.
 134      * @param writer the doclet specific writer.
 135      * @return the new ClassBuilder
 136      */
 137     public static ClassBuilder getInstance(Context context, TypeElement typeElement, ClassWriter writer) {
 138         return new ClassBuilder(context, typeElement, writer);
 139     }
 140 
 141     /**
 142      * {@inheritDoc}
 143      */
 144     @Override
 145     public void build() throws DocletException {
 146         buildClassDoc(contentTree);
 147     }
 148 
 149      /**
 150       * Handles the {@literal <TypeElement>} tag.
 151       *
 152       * @param contentTree the content tree to which the documentation will be added
 153       * @throws DocletException if there is a problem while building the documentation
 154       */
 155      protected void buildClassDoc(Content contentTree) throws DocletException {
 156         String key;
 157         if (isInterface) {
 158             key = "doclet.Interface";
 159         } else if (isEnum) {
 160             key = "doclet.Enum";
 161         } else if (isRecord) {
 162             key = "doclet.Record";
 163         } else {
 164             key = "doclet.Class";
 165         }
 166         contentTree = writer.getHeader(resources.getText(key) + " "
 167                 + utils.getSimpleName(typeElement));
 168         Content classContentTree = writer.getClassContentHeader();
 169 
 170         buildClassTree(classContentTree);
 171         buildClassInfo(classContentTree);
 172         buildMemberSummary(classContentTree);
 173         buildMemberDetails(classContentTree);
 174 
 175         writer.addClassContentTree(contentTree, classContentTree);
 176         writer.addFooter(contentTree);
 177         writer.printDocument(contentTree);
 178         copyDocFiles();
 179     }
 180 
 181      /**
 182       * Build the class tree documentation.
 183       *
 184       * @param classContentTree the content tree to which the documentation will be added
 185       */
 186     protected void buildClassTree(Content classContentTree) {
 187         writer.addClassTree(classContentTree);
 188     }
 189 
 190     /**
 191      * Build the class information tree documentation.
 192      *
 193      * @param classContentTree the content tree to which the documentation will be added
 194      * @throws DocletException if there is a problem while building the documentation
 195      */
 196     protected void buildClassInfo(Content classContentTree) throws DocletException {
 197         Content classInfoTree = new ContentBuilder();
 198         buildParamInfo(classInfoTree);
 199         buildSuperInterfacesInfo(classInfoTree);
 200         buildImplementedInterfacesInfo(classInfoTree);
 201         buildSubClassInfo(classInfoTree);
 202         buildSubInterfacesInfo(classInfoTree);
 203         buildInterfaceUsageInfo(classInfoTree);
 204         buildNestedClassInfo(classInfoTree);
 205         buildFunctionalInterfaceInfo(classInfoTree);
 206         buildClassSignature(classInfoTree);
 207         buildDeprecationInfo(classInfoTree);
 208         buildClassDescription(classInfoTree);
 209         buildClassTagInfo(classInfoTree);
 210 
 211         classContentTree.add(writer.getClassInfo(classInfoTree));
 212     }
 213 
 214     /**
 215      * Build the type parameters and state components of this class.
 216      *
 217      * @param classInfoTree the content tree to which the documentation will be added
 218      */
 219     protected void buildParamInfo(Content classInfoTree) {
 220         writer.addParamInfo(classInfoTree);
 221     }
 222 
 223     /**
 224      * If this is an interface, list all super interfaces.
 225      *
 226      * @param classInfoTree the content tree to which the documentation will be added
 227      */
 228     protected void buildSuperInterfacesInfo(Content classInfoTree) {
 229         writer.addSuperInterfacesInfo(classInfoTree);
 230     }
 231 
 232     /**
 233      * If this is a class, list all interfaces implemented by this class.
 234      *
 235      * @param classInfoTree the content tree to which the documentation will be added
 236      */
 237     protected void buildImplementedInterfacesInfo(Content classInfoTree) {
 238         writer.addImplementedInterfacesInfo(classInfoTree);
 239     }
 240 
 241     /**
 242      * List all the classes extend this one.
 243      *
 244      * @param classInfoTree the content tree to which the documentation will be added
 245      */
 246     protected void buildSubClassInfo(Content classInfoTree) {
 247         writer.addSubClassInfo(classInfoTree);
 248     }
 249 
 250     /**
 251      * List all the interfaces that extend this one.
 252      *
 253      * @param classInfoTree the content tree to which the documentation will be added
 254      */
 255     protected void buildSubInterfacesInfo(Content classInfoTree) {
 256         writer.addSubInterfacesInfo(classInfoTree);
 257     }
 258 
 259     /**
 260      * If this is an interface, list all classes that implement this interface.
 261      *
 262      * @param classInfoTree the content tree to which the documentation will be added
 263      */
 264     protected void buildInterfaceUsageInfo(Content classInfoTree) {
 265         writer.addInterfaceUsageInfo(classInfoTree);
 266     }
 267 
 268     /**
 269      * If this is an functional interface, display appropriate message.
 270      *
 271      * @param classInfoTree the content tree to which the documentation will be added
 272      */
 273     protected void buildFunctionalInterfaceInfo(Content classInfoTree) {
 274         writer.addFunctionalInterfaceInfo(classInfoTree);
 275     }
 276 
 277     /**
 278      * If this class is deprecated, build the appropriate information.
 279      *
 280      * @param classInfoTree the content tree to which the documentation will be added
 281      */
 282     protected void buildDeprecationInfo(Content classInfoTree) {
 283         writer.addClassDeprecationInfo(classInfoTree);
 284     }
 285 
 286     /**
 287      * If this is an inner class or interface, list the enclosing class or interface.
 288      *
 289      * @param classInfoTree the content tree to which the documentation will be added
 290      */
 291     protected void buildNestedClassInfo(Content classInfoTree) {
 292         writer.addNestedClassInfo(classInfoTree);
 293     }
 294 
 295     /**
 296      * Copy the doc files.
 297      *
 298      * @throws DocFileIOException if there is a problem while copying the files
 299      */
 300      private void copyDocFiles() throws DocletException {
 301         PackageElement containingPackage = utils.containingPackage(typeElement);
 302         if ((configuration.packages == null ||
 303             !configuration.packages.contains(containingPackage)) &&
 304             !containingPackagesSeen.contains(containingPackage)) {
 305             //Only copy doc files dir if the containing package is not
 306             //documented AND if we have not documented a class from the same
 307             //package already. Otherwise, we are making duplicate copies.
 308             DocFilesHandler docFilesHandler = configuration
 309                     .getWriterFactory()
 310                     .getDocFilesHandler(containingPackage);
 311             docFilesHandler.copyDocFiles();
 312             containingPackagesSeen.add(containingPackage);
 313         }
 314      }
 315 
 316     /**
 317      * Build the signature of the current class.
 318      *
 319      * @param classInfoTree the content tree to which the documentation will be added
 320      */
 321     protected void buildClassSignature(Content classInfoTree) {
 322         writer.addClassSignature(utils.modifiersToString(typeElement, true), classInfoTree);
 323     }
 324 
 325     /**
 326      * Build the class description.
 327      *
 328      * @param classInfoTree the content tree to which the documentation will be added
 329      */
 330     protected void buildClassDescription(Content classInfoTree) {
 331        writer.addClassDescription(classInfoTree);
 332     }
 333 
 334     /**
 335      * Build the tag information for the current class.
 336      *
 337      * @param classInfoTree the content tree to which the documentation will be added
 338      */
 339     protected void buildClassTagInfo(Content classInfoTree) {
 340        writer.addClassTagInfo(classInfoTree);
 341     }
 342 
 343     /**
 344      * Build the member summary contents of the page.
 345      *
 346      * @param classContentTree the content tree to which the documentation will be added
 347      * @throws DocletException if there is a problem while building the documentation
 348      */
 349     protected void buildMemberSummary(Content classContentTree) throws DocletException {
 350         Content memberSummaryTree = writer.getMemberTreeHeader();
 351         builderFactory.getMemberSummaryBuilder(writer).build(memberSummaryTree);
 352         classContentTree.add(writer.getMemberSummaryTree(memberSummaryTree));
 353     }
 354 
 355     /**
 356      * Build the member details contents of the page.
 357      *
 358      * @param classContentTree the content tree to which the documentation will be added
 359      * @throws DocletException if there is a problem while building the documentation
 360      */
 361     protected void buildMemberDetails(Content classContentTree) throws DocletException {
 362         Content memberDetailsTree = writer.getMemberTreeHeader();
 363 
 364         buildEnumConstantsDetails(memberDetailsTree);
 365         buildPropertyDetails(memberDetailsTree);
 366         buildFieldDetails(memberDetailsTree);
 367         buildConstructorDetails(memberDetailsTree);
 368         buildMethodDetails(memberDetailsTree);
 369 
 370         classContentTree.add(writer.getMemberDetailsTree(memberDetailsTree));
 371     }
 372 
 373     /**
 374      * Build the enum constants documentation.
 375      *
 376      * @param memberDetailsTree the content tree to which the documentation will be added
 377      * @throws DocletException if there is a problem while building the documentation
 378      */
 379     protected void buildEnumConstantsDetails(Content memberDetailsTree) throws DocletException {
 380         builderFactory.getEnumConstantsBuilder(writer).build(memberDetailsTree);
 381     }
 382 
 383     /**
 384      * Build the field documentation.
 385      *
 386      * @param memberDetailsTree the content tree to which the documentation will be added
 387      * @throws DocletException if there is a problem while building the documentation
 388      */
 389     protected void buildFieldDetails(Content memberDetailsTree) throws DocletException {
 390         builderFactory.getFieldBuilder(writer).build(memberDetailsTree);
 391     }
 392 
 393     /**
 394      * Build the property documentation.
 395      *
 396      * @param memberDetailsTree the content tree to which the documentation will be added
 397      * @throws DocletException if there is a problem while building the documentation
 398      */
 399     public void buildPropertyDetails( Content memberDetailsTree) throws DocletException {
 400         builderFactory.getPropertyBuilder(writer).build(memberDetailsTree);
 401     }
 402 
 403     /**
 404      * Build the constructor documentation.
 405      *
 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     protected void buildConstructorDetails(Content memberDetailsTree) throws DocletException {
 410         builderFactory.getConstructorBuilder(writer).build(memberDetailsTree);
 411     }
 412 
 413     /**
 414      * Build the method documentation.
 415      *
 416      * @param memberDetailsTree the content tree to which the documentation will be added
 417      * @throws DocletException if there is a problem while building the documentation
 418      */
 419     protected void buildMethodDetails(Content memberDetailsTree) throws DocletException {
 420         builderFactory.getMethodBuilder(writer).build(memberDetailsTree);
 421     }
 422 
 423     /**
 424      * The documentation for values() and valueOf() in Enums are set by the
 425      * doclet only iff the user or overridden methods are missing.
 426      * @param elem the enum element
 427      */
 428     private void setEnumDocumentation(TypeElement elem) {
 429         CommentUtils cmtUtils = configuration.cmtUtils;
 430         for (ExecutableElement ee : utils.getMethods(elem)) {
 431             if (!utils.getFullBody(ee).isEmpty()) // ignore if already set
 432                 continue;
 433             Name name = ee.getSimpleName();
 434             if (name.contentEquals("values") && ee.getParameters().isEmpty()) {
 435                 utils.removeCommentHelper(ee); // purge previous entry
 436                 cmtUtils.setEnumValuesTree(ee);
 437             } else if (name.contentEquals("valueOf") && ee.getParameters().size() == 1) {
 438                 // TODO: check parameter type
 439                 utils.removeCommentHelper(ee); // purge previous entry
 440                 cmtUtils.setEnumValueOfTree(ee);
 441             }
 442         }
 443     }
 444 
 445     /**
 446      * Sets the documentation as needed for the mandated parts of a record type.
 447      * This includes the canonical constructor, methods like {@code equals},
 448      * {@code hashCode}, {@code toString}, the accessor methods, and the underlying
 449      * field.
 450      * @param elem the record element
 451      */
 452 
 453     private void setRecordDocumentation(TypeElement elem) {
 454         CommentUtils cmtUtils = configuration.cmtUtils;
 455         Set<Name> componentNames = elem.getStateComponents().stream()
 456                 .map(Element::getSimpleName)
 457                 .collect(Collectors.toSet());
 458 
 459         for (ExecutableElement ee : utils.getConstructors(elem)) {
 460             if (utils.isCanonicalRecordConstructor(ee)) {
 461                 if (utils.getFullBody(ee).isEmpty()) {
 462                     utils.removeCommentHelper(ee); // purge previous entry
 463                     cmtUtils.setRecordConstructorTree(ee);
 464                 }
 465                 // only one canonical constructor; no longer need to keep looking
 466                 break;
 467             }
 468         }
 469 
 470         for (VariableElement ve : utils.getFields(elem)) {
 471             // The fields for the state component cannot be declared by the
 472             // user and so cannot have any pre-existing comment.
 473             Name name = ve.getSimpleName();
 474             if (componentNames.contains(name)) {
 475                 utils.removeCommentHelper(ve); // purge previous entry
 476                 cmtUtils.setRecordFieldTree(ve);
 477             }
 478         }
 479 
 480         TypeMirror objectType = utils.elementUtils.getTypeElement("java.lang.Object").asType();
 481 
 482         for (ExecutableElement ee : utils.getMethods(elem)) {
 483             if (!utils.getFullBody(ee).isEmpty()) {
 484                 continue;
 485             }
 486 
 487             Name name = ee.getSimpleName();
 488             List<? extends VariableElement> params = ee.getParameters();
 489             if (name.contentEquals("equals")) {
 490                 if (params.size() == 1 && utils.typeUtils.isSameType(params.get(0).asType(), objectType)) {
 491                     utils.removeCommentHelper(ee); // purge previous entry
 492                     cmtUtils.setRecordEqualsTree(ee);
 493                 }
 494             } else if (name.contentEquals("hashCode")) {
 495                 if (params.isEmpty()) {
 496                     utils.removeCommentHelper(ee); // purge previous entry
 497                     cmtUtils.setRecordHashCodeTree(ee);
 498                 }
 499             } else if (name.contentEquals("toString")) {
 500                 if (params.isEmpty()) {
 501                     utils.removeCommentHelper(ee); // purge previous entry
 502                     cmtUtils.setRecordToStringTree(ee);
 503                 }
 504             } else if (componentNames.contains(name)) {
 505                 if (params.isEmpty()) {
 506                     utils.removeCommentHelper(ee); // purge previous entry
 507                     cmtUtils.setRecordAccessorTree(ee);
 508                 }
 509             }
 510         }
 511 
 512     }
 513 }