< prev index next >

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/builders/ClassBuilder.java

Print this page




   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 javax.lang.model.element.PackageElement;
  29 import javax.lang.model.element.TypeElement;



  30 


  31 import jdk.javadoc.internal.doclets.formats.html.markup.ContentBuilder;
  32 import jdk.javadoc.internal.doclets.toolkit.ClassWriter;

  33 import jdk.javadoc.internal.doclets.toolkit.Content;
  34 import jdk.javadoc.internal.doclets.toolkit.DocFilesHandler;
  35 import jdk.javadoc.internal.doclets.toolkit.DocletException;
  36 import jdk.javadoc.internal.doclets.toolkit.util.DocFileIOException;
  37 import jdk.javadoc.internal.doclets.toolkit.util.Utils;
  38 
  39 /**
  40  * Builds the summary for a given class.
  41  *
  42  *  <p><b>This is NOT part of any supported API.
  43  *  If you write code that depends on this, you do so at your own risk.
  44  *  This code and its internal interfaces are subject to change or
  45  *  deletion without notice.</b>
  46  *
  47  * @author Jamie Ho
  48  * @author Bhavesh Patel (Modified)
  49  */
  50 public class ClassBuilder extends AbstractBuilder {
  51 
  52     /**
  53      * The class being documented.
  54      */
  55     private final TypeElement typeElement;
  56 
  57     /**
  58      * The doclet specific writer.
  59      */
  60     private final ClassWriter writer;
  61 
  62     /**
  63      * Keep track of whether or not this typeElement is an interface.
  64      */
  65     private final boolean isInterface;
  66 
  67     /**
  68      * Keep track of whether or not this typeElement 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     private final Utils utils;
  78 
  79     /**
  80      * Construct a new ClassBuilder.
  81      *
  82      * @param context  the build context
  83      * @param typeElement the class being documented.
  84      * @param writer the doclet specific writer.
  85      */
  86     private ClassBuilder(Context context, TypeElement typeElement, ClassWriter writer) {
  87         super(context);
  88         this.typeElement = typeElement;
  89         this.writer = writer;
  90         this.utils = configuration.utils;
  91         if (utils.isInterface(typeElement)) {
  92             isInterface = true;
  93             isEnum = false;

  94         } else if (utils.isEnum(typeElement)) {
  95             isInterface = false;
  96             isEnum = true;
  97             utils.setEnumDocumentation(typeElement);






  98         } else {
  99             isInterface = false;
 100             isEnum = false;

 101         }
 102     }
 103 
 104     /**
 105      * Constructs a new ClassBuilder.
 106      *
 107      * @param context  the build context
 108      * @param typeElement the class being documented.
 109      * @param writer the doclet specific writer.
 110      * @return the new ClassBuilder
 111      */
 112     public static ClassBuilder getInstance(Context context, TypeElement typeElement, ClassWriter writer) {
 113         return new ClassBuilder(context, typeElement, writer);
 114     }
 115 
 116     /**
 117      * {@inheritDoc}
 118      */
 119     @Override
 120     public void build() throws DocletException {
 121         buildClassDoc(contentTree);
 122     }
 123 
 124      /**
 125       * Handles the {@literal <TypeElement>} tag.
 126       *
 127       * @param contentTree the content tree to which the documentation will be added
 128       * @throws DocletException if there is a problem while building the documentation
 129       */
 130      protected void buildClassDoc(Content contentTree) throws DocletException {
 131         String key;
 132         if (isInterface) {
 133             key = "doclet.Interface";
 134         } else if (isEnum) {
 135             key = "doclet.Enum";


 136         } else {
 137             key = "doclet.Class";
 138         }
 139         contentTree = writer.getHeader(resources.getText(key) + " "
 140                 + utils.getSimpleName(typeElement));
 141         Content classContentTree = writer.getClassContentHeader();
 142 
 143         buildClassTree(classContentTree);
 144         buildClassInfo(classContentTree);
 145         buildMemberSummary(classContentTree);
 146         buildMemberDetails(classContentTree);
 147 
 148         writer.addClassContentTree(contentTree, classContentTree);
 149         writer.addFooter(contentTree);
 150         writer.printDocument(contentTree);
 151         copyDocFiles();
 152     }
 153 
 154      /**
 155       * Build the class tree documentation.
 156       *
 157       * @param classContentTree the content tree to which the documentation will be added
 158       */
 159     protected void buildClassTree(Content classContentTree) {
 160         writer.addClassTree(classContentTree);
 161     }
 162 
 163     /**
 164      * Build the class information tree documentation.
 165      *
 166      * @param classContentTree the content tree to which the documentation will be added
 167      * @throws DocletException if there is a problem while building the documentation
 168      */
 169     protected void buildClassInfo(Content classContentTree) throws DocletException {
 170         Content classInfoTree = new ContentBuilder();
 171         buildTypeParamInfo(classInfoTree);
 172         buildSuperInterfacesInfo(classInfoTree);
 173         buildImplementedInterfacesInfo(classInfoTree);
 174         buildSubClassInfo(classInfoTree);
 175         buildSubInterfacesInfo(classInfoTree);
 176         buildInterfaceUsageInfo(classInfoTree);
 177         buildNestedClassInfo(classInfoTree);
 178         buildFunctionalInterfaceInfo(classInfoTree);
 179         buildClassSignature(classInfoTree);
 180         buildDeprecationInfo(classInfoTree);
 181         buildClassDescription(classInfoTree);
 182         buildClassTagInfo(classInfoTree);
 183 
 184         classContentTree.add(writer.getClassInfo(classInfoTree));
 185     }
 186 
 187     /**
 188      * Build the type parameters of this class.
 189      *
 190      * @param classInfoTree the content tree to which the documentation will be added
 191      */
 192     protected void buildTypeParamInfo(Content classInfoTree) {
 193         writer.addTypeParamInfo(classInfoTree);
 194     }
 195 
 196     /**
 197      * If this is an interface, list all super interfaces.
 198      *
 199      * @param classInfoTree the content tree to which the documentation will be added
 200      */
 201     protected void buildSuperInterfacesInfo(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 classInfoTree the content tree to which the documentation will be added
 209      */
 210     protected void buildImplementedInterfacesInfo(Content classInfoTree) {
 211         writer.addImplementedInterfacesInfo(classInfoTree);
 212     }
 213 


 374     }
 375 
 376     /**
 377      * Build the constructor documentation.
 378      *
 379      * @param memberDetailsTree the content tree to which the documentation will be added
 380      * @throws DocletException if there is a problem while building the documentation
 381      */
 382     protected void buildConstructorDetails(Content memberDetailsTree) throws DocletException {
 383         builderFactory.getConstructorBuilder(writer).build(memberDetailsTree);
 384     }
 385 
 386     /**
 387      * Build the method documentation.
 388      *
 389      * @param memberDetailsTree the content tree to which the documentation will be added
 390      * @throws DocletException if there is a problem while building the documentation
 391      */
 392     protected void buildMethodDetails(Content memberDetailsTree) throws DocletException {
 393         builderFactory.getMethodBuilder(writer).build(memberDetailsTree);



























































































 394     }
 395 }


   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 


 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 }
< prev index next >