jdk8-mips64-public/langtools: src/share/classes/com/sun/tools/doclets/internal/toolkit/builders/MemberSummaryBuilder.java@c75be5bc5283

     1 /*

     2  * Copyright (c) 2003, 2012, 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  */

    26 package com.sun.tools.doclets.internal.toolkit.builders;

    28 import java.util.*;

    30 import com.sun.javadoc.*;

    31 import com.sun.tools.doclets.internal.toolkit.*;

    32 import com.sun.tools.doclets.internal.toolkit.util.*;

    34 /**

    35  * Builds the member summary.

    36  *

    37  * This code is not part of an API.

    38  * It is implementation that is subject to change.

    39  * Do not use it as an API

    40  *

    41  * @author Jamie Ho

    42  * @author Bhavesh Patel (Modified)

    43  * @since 1.5

    44  */

    45 public class MemberSummaryBuilder extends AbstractMemberBuilder {

    47     /**

    48      * The XML root for this builder.

    49      */

    50     public static final String NAME = "MemberSummary";

    52     /**

    53      * The visible members for the given class.

    54      */

    55     private VisibleMemberMap[] visibleMemberMaps;

    57     /**

    58      * The member summary writers for the given class.

    59      */

    60     private MemberSummaryWriter[] memberSummaryWriters;

    62     /**

    63      * The type being documented.

    64      */

    65     private ClassDoc classDoc;

    67     private MemberSummaryBuilder(Configuration configuration) {

    68         super(configuration);

    69     }

    71     /**

    72      * Construct a new MemberSummaryBuilder.

    73      *

    74      * @param classWriter   the writer for the class whose members are being

    75      *                      summarized.

    76      * @param configuration the current configuration of the doclet.

    77      */

    78     public static MemberSummaryBuilder getInstance(

    79             ClassWriter classWriter, Configuration configuration)

    80             throws Exception {

    81         MemberSummaryBuilder builder = new MemberSummaryBuilder(configuration);

    82         builder.classDoc = classWriter.getClassDoc();

    83         builder.init(classWriter);

    84         return builder;

    85     }

    87     /**

    88      * Construct a new MemberSummaryBuilder.

    89      *

    90      * @param annotationTypeWriter the writer for the class whose members are

    91      *                             being summarized.

    92      * @param configuration the current configuration of the doclet.

    93      */

    94     public static MemberSummaryBuilder getInstance(

    95             AnnotationTypeWriter annotationTypeWriter, Configuration configuration)

    96             throws Exception {

    97         MemberSummaryBuilder builder = new MemberSummaryBuilder(configuration);

    98         builder.classDoc = annotationTypeWriter.getAnnotationTypeDoc();

    99         builder.init(annotationTypeWriter);

   100         return builder;

   101     }

   103     private void init(Object writer) throws Exception {

   104         visibleMemberMaps =

   105                 new VisibleMemberMap[VisibleMemberMap.NUM_MEMBER_TYPES];

   106         for (int i = 0; i < VisibleMemberMap.NUM_MEMBER_TYPES; i++) {

   107             visibleMemberMaps[i] =

   108                     new VisibleMemberMap(

   109                     classDoc,

   110                     i,

   111                     configuration.nodeprecated);

   112         }

   113         memberSummaryWriters =

   114                 new MemberSummaryWriter[VisibleMemberMap.NUM_MEMBER_TYPES];

   115         for (int i = 0; i < VisibleMemberMap.NUM_MEMBER_TYPES; i++) {

   116             if (classDoc.isAnnotationType()) {

   117                 memberSummaryWriters[i] =

   118                     visibleMemberMaps[i].noVisibleMembers()?

   119                         null :

   120                         configuration.getWriterFactory().getMemberSummaryWriter(

   121                         (AnnotationTypeWriter) writer, i);

   122             } else {

   123                 memberSummaryWriters[i] =

   124                     visibleMemberMaps[i].noVisibleMembers()?

   125                         null :

   126                         configuration.getWriterFactory().getMemberSummaryWriter(

   127                         (ClassWriter) writer, i);

   128             }

   129         }

   131     }

   133     /**

   134      * {@inheritDoc}

   135      */

   136     public String getName() {

   137         return NAME;

   138     }

   140     /**

   141      * Return the specified visible member map.

   142      *

   143      * @param type the type of visible member map to return.

   144      * @return the specified visible member map.

   145      * @throws ArrayIndexOutOfBoundsException when the type is invalid.

   146      * @see VisibleMemberMap

   147      */

   148     public VisibleMemberMap getVisibleMemberMap(int type) {

   149         return visibleMemberMaps[type];

   150     }

   152     /**

   153      * Return the specified member summary writer.

   154      *

   155      * @param type the type of member summary writer to return.

   156      * @return the specified member summary writer.

   157      * @throws ArrayIndexOutOfBoundsException when the type is invalid.

   158      * @see VisibleMemberMap

   159      */

   160     public MemberSummaryWriter getMemberSummaryWriter(int type) {

   161         return memberSummaryWriters[type];

   162     }

   164     /**

   165      * Returns a list of methods that will be documented for the given class.

   166      * This information can be used for doclet specific documentation

   167      * generation.

   168      *

   169      * @param classDoc the {@link ClassDoc} we want to check.

   170      * @param type the type of members to return.

   171      * @return a list of methods that will be documented.

   172      * @see VisibleMemberMap

   173      */

   174     public List<ProgramElementDoc> members(int type) {

   175         return visibleMemberMaps[type].getLeafClassMembers(configuration);

   176     }

   178     /**

   179      * Return true it there are any members to summarize.

   180      *

   181      * @return true if there are any members to summarize.

   182      */

   183     public boolean hasMembersToDocument() {

   184         if (classDoc instanceof AnnotationTypeDoc) {

   185             return ((AnnotationTypeDoc) classDoc).elements().length > 0;

   186         }

   187         for (int i = 0; i < VisibleMemberMap.NUM_MEMBER_TYPES; i++) {

   188             VisibleMemberMap members = visibleMemberMaps[i];

   189             if (!members.noVisibleMembers()) {

   190                 return true;

   191             }

   192         }

   193         return false;

   194     }

   196     /**

   197      * Build the summary for the enum constants.

   198      *

   199      * @param node the XML element that specifies which components to document

   200      * @param memberSummaryTree the content tree to which the documentation will be added

   201      */

   202     public void buildEnumConstantsSummary(XMLNode node, Content memberSummaryTree) {

   203         MemberSummaryWriter writer =

   204                 memberSummaryWriters[VisibleMemberMap.ENUM_CONSTANTS];

   205         VisibleMemberMap visibleMemberMap =

   206                 visibleMemberMaps[VisibleMemberMap.ENUM_CONSTANTS];

   207         addSummary(writer, visibleMemberMap, false, memberSummaryTree);

   208     }

   210     /**

   211      * Build the summary for the optional members.

   212      *

   213      * @param node the XML element that specifies which components to document

   214      * @param memberSummaryTree the content tree to which the documentation will be added

   215      */

   216     public void buildAnnotationTypeOptionalMemberSummary(XMLNode node, Content memberSummaryTree) {

   217         MemberSummaryWriter writer =

   218                 memberSummaryWriters[VisibleMemberMap.ANNOTATION_TYPE_MEMBER_OPTIONAL];

   219         VisibleMemberMap visibleMemberMap =

   220                 visibleMemberMaps[VisibleMemberMap.ANNOTATION_TYPE_MEMBER_OPTIONAL];

   221         addSummary(writer, visibleMemberMap, false, memberSummaryTree);

   222     }

   224     /**

   225      * Build the summary for the optional members.

   226      *

   227      * @param node the XML element that specifies which components to document

   228      * @param memberSummaryTree the content tree to which the documentation will be added

   229      */

   230     public void buildAnnotationTypeRequiredMemberSummary(XMLNode node, Content memberSummaryTree) {

   231         MemberSummaryWriter writer =

   232                 memberSummaryWriters[VisibleMemberMap.ANNOTATION_TYPE_MEMBER_REQUIRED];

   233         VisibleMemberMap visibleMemberMap =

   234                 visibleMemberMaps[VisibleMemberMap.ANNOTATION_TYPE_MEMBER_REQUIRED];

   235         addSummary(writer, visibleMemberMap, false, memberSummaryTree);

   236     }

   238     /**

   239      * Build the summary for the fields.

   240      *

   241      * @param node the XML element that specifies which components to document

   242      * @param memberSummaryTree the content tree to which the documentation will be added

   243      */

   244     public void buildFieldsSummary(XMLNode node, Content memberSummaryTree) {

   245         MemberSummaryWriter writer =

   246                 memberSummaryWriters[VisibleMemberMap.FIELDS];

   247         VisibleMemberMap visibleMemberMap =

   248                 visibleMemberMaps[VisibleMemberMap.FIELDS];

   249         addSummary(writer, visibleMemberMap, true, memberSummaryTree);

   250     }

   252     /**

   253      * Build the summary for the nested classes.

   254      *

   255      * @param node the XML element that specifies which components to document

   256      * @param memberSummaryTree the content tree to which the documentation will be added

   257      */

   258     public void buildNestedClassesSummary(XMLNode node, Content memberSummaryTree) {

   259         MemberSummaryWriter writer =

   260                 memberSummaryWriters[VisibleMemberMap.INNERCLASSES];

   261         VisibleMemberMap visibleMemberMap =

   262                 visibleMemberMaps[VisibleMemberMap.INNERCLASSES];

   263         addSummary(writer, visibleMemberMap, true, memberSummaryTree);

   264     }

   266     /**

   267      * Build the method summary.

   268      *

   269      * @param node the XML element that specifies which components to document

   270      * @param memberSummaryTree the content tree to which the documentation will be added

   271      */

   272     public void buildMethodsSummary(XMLNode node, Content memberSummaryTree) {

   273         MemberSummaryWriter writer =

   274                 memberSummaryWriters[VisibleMemberMap.METHODS];

   275         VisibleMemberMap visibleMemberMap =

   276                 visibleMemberMaps[VisibleMemberMap.METHODS];

   277         addSummary(writer, visibleMemberMap, true, memberSummaryTree);

   278     }

   280     /**

   281      * Build the constructor summary.

   282      *

   283      * @param node the XML element that specifies which components to document

   284      * @param memberSummaryTree the content tree to which the documentation will be added

   285      */

   286     public void buildConstructorsSummary(XMLNode node, Content memberSummaryTree) {

   287         MemberSummaryWriter writer =

   288                 memberSummaryWriters[VisibleMemberMap.CONSTRUCTORS];

   289         VisibleMemberMap visibleMemberMap =

   290                 visibleMemberMaps[VisibleMemberMap.CONSTRUCTORS];

   291         addSummary(writer, visibleMemberMap, false, memberSummaryTree);

   292     }

   294     /**

   295      * Build the member summary for the given members.

   296      *

   297      * @param writer the summary writer to write the output.

   298      * @param visibleMemberMap the given members to summarize.

   299      * @param summaryTreeList list of content trees to which the documentation will be added

   300      */

   301     private void buildSummary(MemberSummaryWriter writer,

   302             VisibleMemberMap visibleMemberMap, LinkedList<Content> summaryTreeList) {

   303         List<ProgramElementDoc> members = new ArrayList<ProgramElementDoc>(visibleMemberMap.getLeafClassMembers(

   304                 configuration));

   305         if (members.size() > 0) {

   306             Collections.sort(members);

   307             Content tableTree = writer.getSummaryTableTree(classDoc);

   308             for (int i = 0; i < members.size(); i++) {

   309                 ProgramElementDoc member = members.get(i);

   310                 Tag[] firstSentenceTags = member.firstSentenceTags();

   311                 if (member instanceof MethodDoc && firstSentenceTags.length == 0) {

   312                     //Inherit comments from overriden or implemented method if

   313                     //necessary.

   314                     DocFinder.Output inheritedDoc =

   315                             DocFinder.search(new DocFinder.Input((MethodDoc) member));

   316                     if (inheritedDoc.holder != null &&

   317                             inheritedDoc.holder.firstSentenceTags().length > 0) {

   318                         firstSentenceTags = inheritedDoc.holder.firstSentenceTags();

   319                     }

   320                 }

   321                 writer.addMemberSummary(classDoc, member, firstSentenceTags, tableTree, i);

   322             }

   323             summaryTreeList.add(tableTree);

   324         }

   325     }

   327     /**

   328      * Build the inherited member summary for the given methods.

   329      *

   330      * @param writer the writer for this member summary.

   331      * @param visibleMemberMap the map for the members to document.

   332      * @param summaryTreeList list of content trees to which the documentation will be added

   333      */

   334     private void buildInheritedSummary(MemberSummaryWriter writer,

   335             VisibleMemberMap visibleMemberMap, LinkedList<Content> summaryTreeList) {

   336         for (Iterator<ClassDoc> iter = visibleMemberMap.getVisibleClassesList().iterator();

   337                 iter.hasNext();) {

   338             ClassDoc inhclass = iter.next();

   339             if (! (inhclass.isPublic() ||

   340                     Util.isLinkable(inhclass, configuration))) {

   341                 continue;

   342             }

   343             if (inhclass == classDoc) {

   344                 continue;

   345             }

   346             List<ProgramElementDoc> inhmembers = visibleMemberMap.getMembersFor(inhclass);

   347             if (inhmembers.size() > 0) {

   348                 Collections.sort(inhmembers);

   349                 Content inheritedTree = writer.getInheritedSummaryHeader(inhclass);

   350                 Content linksTree = writer.getInheritedSummaryLinksTree();

   351                 for (int j = 0; j < inhmembers.size(); ++j) {

   352                     writer.addInheritedMemberSummary(

   353                             inhclass.isPackagePrivate() &&

   354                             ! Util.isLinkable(inhclass, configuration) ?

   355                             classDoc : inhclass,

   356                             inhmembers.get(j),

   357                             j == 0,

   358                             j == inhmembers.size() - 1, linksTree);

   359                 }

   360                 inheritedTree.addContent(linksTree);

   361                 summaryTreeList.add(writer.getMemberTree(inheritedTree));

   362             }

   363         }

   364     }

   366     /**

   367      * Add the summary for the documentation.

   368      *

   369      * @param writer the writer for this member summary.

   370      * @param visibleMemberMap the map for the members to document.

   371      * @param showInheritedSummary true if inherited summary should be documented

   372      * @param memberSummaryTree the content tree to which the documentation will be added

   373      */

   374     private void addSummary(MemberSummaryWriter writer,

   375             VisibleMemberMap visibleMemberMap, boolean showInheritedSummary,

   376             Content memberSummaryTree) {

   377         LinkedList<Content> summaryTreeList = new LinkedList<Content>();

   378         buildSummary(writer, visibleMemberMap, summaryTreeList);

   379         if (showInheritedSummary)

   380             buildInheritedSummary(writer, visibleMemberMap, summaryTreeList);

   381         if (!summaryTreeList.isEmpty()) {

   382             Content memberTree = writer.getMemberSummaryHeader(

   383                     classDoc, memberSummaryTree);

   384             for (int i = 0; i < summaryTreeList.size(); i++) {

   385                 memberTree.addContent(summaryTreeList.get(i));

   386             }

   387             memberSummaryTree.addContent(writer.getMemberTree(memberTree));

   388         }

   389     }

   390 }

Mercurial > jdk8-mips64-public > langtools / file revision

src/share/classes/com/sun/tools/doclets/internal/toolkit/builders/MemberSummaryBuilder.java@c75be5bc5283

src/share/classes/com/sun/tools/doclets/internal/toolkit/builders/MemberSummaryBuilder.java