jdk-sandbox: comparison src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/builders/MemberSummaryBuilder.java

equal deleted inserted replaced

-:2422d4e027b0
+:601277b1d582
 /*
-* Copyright (c) 2003, 2017, Oracle and/or its affiliates. All rights reserved.
+* Copyright (c) 2003, 2018, Oracle and/or its affiliates. All rights reserved.
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
 *
 * This code is free software; you can redistribute it and/or modify it
 * under the terms of the GNU General Public License version 2 only, as
 * published by the Free Software Foundation.  Oracle designates this
 package jdk.javadoc.internal.doclets.toolkit.builders;
 import java.text.MessageFormat;
 import java.util.*;
+import java.util.stream.Collectors;
 import javax.lang.model.element.Element;
 import javax.lang.model.element.ExecutableElement;
 import javax.lang.model.element.TypeElement;
 import javax.lang.model.element.VariableElement;
+import javax.lang.model.util.ElementFilter;
+import com.sun.source.doctree.DocCommentTree;
 import com.sun.source.doctree.DocTree;
 import com.sun.source.doctree.DocTree.Kind;
 import jdk.javadoc.internal.doclets.toolkit.AnnotationTypeWriter;
 import jdk.javadoc.internal.doclets.toolkit.ClassWriter;
 import jdk.javadoc.internal.doclets.toolkit.Content;
 import jdk.javadoc.internal.doclets.toolkit.MemberSummaryWriter;
 import jdk.javadoc.internal.doclets.toolkit.WriterFactory;
 import jdk.javadoc.internal.doclets.toolkit.util.CommentHelper;
 import jdk.javadoc.internal.doclets.toolkit.util.DocFinder;
-import jdk.javadoc.internal.doclets.toolkit.util.VisibleMemberMap;
+import jdk.javadoc.internal.doclets.toolkit.util.VisibleMemberTable;
 import jdk.javadoc.internal.doclets.toolkit.CommentUtils;
+import static jdk.javadoc.internal.doclets.toolkit.util.VisibleMemberTable.Kind.*;
 /**
 * Builds the member summary.
 * There are two anonymous subtype variants of this builder, created
 * in the {@link #getInstance} methods. One is for general types;
 private final Comparator<Element> comparator;
 /**
 * The member summary writers for the given class.
 */
-private final EnumMap<VisibleMemberMap.Kind, MemberSummaryWriter> memberSummaryWriters;
+private final EnumMap<VisibleMemberTable.Kind, MemberSummaryWriter> memberSummaryWriters;
-/**
+final PropertyHelper pHelper;
-* The type being documented.
-*/
-protected final TypeElement typeElement;
 /**
 * Construct a new MemberSummaryBuilder.
 *
 * @param context       the build context.
 * @param typeElement   the type element.
 */
 private MemberSummaryBuilder(Context context, TypeElement typeElement) {
-super(context);
+super(context, typeElement);
-this.typeElement = typeElement;
+memberSummaryWriters = new EnumMap<>(VisibleMemberTable.Kind.class);
-memberSummaryWriters = new EnumMap<>(VisibleMemberMap.Kind.class);
+comparator = utils.makeIndexUseComparator();
+pHelper = new PropertyHelper(this);
-comparator = utils.makeGeneralPurposeComparator();
 }
 /**
 * Construct a new MemberSummaryBuilder for a general type.
 *
 buildMethodsSummary(contentTree);
 }
 @Override
 public boolean hasMembersToDocument() {
-for (VisibleMemberMap.Kind kind : VisibleMemberMap.Kind.values()) {
+return visibleMemberTable.hasVisibleMembers();
-VisibleMemberMap members = getVisibleMemberMap(kind);
-if (!members.noVisibleMembers()) {
-return true;
-}
-}
-return false;
 }
 };
 WriterFactory wf = context.configuration.getWriterFactory();
-for (VisibleMemberMap.Kind kind : VisibleMemberMap.Kind.values()) {
+for (VisibleMemberTable.Kind kind : VisibleMemberTable.Kind.values()) {
-MemberSummaryWriter msw = builder.getVisibleMemberMap(kind).noVisibleMembers()
+MemberSummaryWriter msw = builder.getVisibleMemberTable().hasVisibleMembers(kind)
-? null
+? wf.getMemberSummaryWriter(classWriter, kind)
-: wf.getMemberSummaryWriter(classWriter, kind);
+: null;
 builder.memberSummaryWriters.put(kind, msw);
 }
 return builder;
 }
 public boolean hasMembersToDocument() {
 return !utils.getAnnotationMembers(typeElement).isEmpty();
 }
 };
 WriterFactory wf = context.configuration.getWriterFactory();
-for (VisibleMemberMap.Kind kind : VisibleMemberMap.Kind.values()) {
+for (VisibleMemberTable.Kind kind : VisibleMemberTable.Kind.values()) {
-MemberSummaryWriter msw = builder.getVisibleMemberMap(kind).noVisibleMembers()
+MemberSummaryWriter msw = builder.getVisibleMemberTable().hasVisibleMembers(kind)
-? null
+? wf.getMemberSummaryWriter(annotationTypeWriter, kind)
-: wf.getMemberSummaryWriter(annotationTypeWriter, kind);
+: null;
 builder.memberSummaryWriters.put(kind, msw);
 }
 return builder;
 }
 /**
 * Return the specified visible member map.
 *
-* @param kind the kind of visible member map to return.
 * @return the specified visible member map.
 * @throws ArrayIndexOutOfBoundsException when the type is invalid.
-* @see VisibleMemberMap
+* @see VisibleMemberTable
 */
-public VisibleMemberMap getVisibleMemberMap(VisibleMemberMap.Kind kind) {
+public VisibleMemberTable getVisibleMemberTable() {
-return configuration.getVisibleMemberMap(typeElement, kind);
+return visibleMemberTable;
 }
 /**.
 * Return the specified member summary writer.
 *
 * @param kind the kind of member summary writer to return.
 * @return the specified member summary writer.
 * @throws ArrayIndexOutOfBoundsException when the type is invalid.
-* @see VisibleMemberMap
+* @see VisibleMemberTable
 */
-public MemberSummaryWriter getMemberSummaryWriter(VisibleMemberMap.Kind kind) {
+public MemberSummaryWriter getMemberSummaryWriter(VisibleMemberTable.Kind kind) {
 return memberSummaryWriters.get(kind);
 }
 /**
 * Returns a list of methods that will be documented for the given class.
 * This information can be used for doclet specific documentation
 * generation.
 *
 * @param kind the kind of elements to return.
 * @return a list of methods that will be documented.
-* @see VisibleMemberMap
+* @see VisibleMemberTable
 */
-public SortedSet<Element> members(VisibleMemberMap.Kind kind) {
+public SortedSet<Element> members(VisibleMemberTable.Kind kind) {
 TreeSet<Element> out = new TreeSet<>(comparator);
-out.addAll(getVisibleMemberMap(kind).getLeafMembers());
+out.addAll(getVisibleMembers(kind));
 return out;
 }
 /**
+* Returns true if there are members of the given kind, false otherwise.
+* @param kind
+* @return true if there are members of the given kind, false otherwise
+*/
+public boolean hasMembers(VisibleMemberTable.Kind kind) {
+return !getVisibleMembers(kind).isEmpty();
+}
+/**
 * Build the summary for the enum constants.
 *
 * @param memberSummaryTree the content tree to which the documentation will be added
 */
 protected void buildEnumConstantsSummary(Content memberSummaryTree) {
-MemberSummaryWriter writer =
+MemberSummaryWriter writer = memberSummaryWriters.get(ENUM_CONSTANTS);
-memberSummaryWriters.get(VisibleMemberMap.Kind.ENUM_CONSTANTS);
+addSummary(writer, ENUM_CONSTANTS, false, memberSummaryTree);
-VisibleMemberMap visibleMemberMap =
-getVisibleMemberMap(VisibleMemberMap.Kind.ENUM_CONSTANTS);
-addSummary(writer, visibleMemberMap, false, memberSummaryTree);
 }
 /**
 * Build the summary for fields.
 *
 * @param memberSummaryTree the content tree to which the documentation will be added
 */
 protected void buildAnnotationTypeFieldsSummary(Content memberSummaryTree) {
-MemberSummaryWriter writer =
+MemberSummaryWriter writer = memberSummaryWriters.get(ANNOTATION_TYPE_FIELDS);
-memberSummaryWriters.get(VisibleMemberMap.Kind.ANNOTATION_TYPE_FIELDS);
+addSummary(writer, ANNOTATION_TYPE_FIELDS, false, memberSummaryTree);
-VisibleMemberMap visibleMemberMap =
-getVisibleMemberMap(VisibleMemberMap.Kind.ANNOTATION_TYPE_FIELDS);
-addSummary(writer, visibleMemberMap, false, memberSummaryTree);
 }
 /**
 * Build the summary for the optional members.
 *
 * @param memberSummaryTree the content tree to which the documentation will be added
 */
 protected void buildAnnotationTypeOptionalMemberSummary(Content memberSummaryTree) {
-MemberSummaryWriter writer =
+MemberSummaryWriter writer = memberSummaryWriters.get(ANNOTATION_TYPE_MEMBER_OPTIONAL);
-memberSummaryWriters.get(VisibleMemberMap.Kind.ANNOTATION_TYPE_MEMBER_OPTIONAL);
+addSummary(writer, ANNOTATION_TYPE_MEMBER_OPTIONAL, false, memberSummaryTree);
-VisibleMemberMap visibleMemberMap =
-getVisibleMemberMap(VisibleMemberMap.Kind.ANNOTATION_TYPE_MEMBER_OPTIONAL);
-addSummary(writer, visibleMemberMap, false, memberSummaryTree);
 }
 /**
 * Build the summary for the optional members.
 *
 * @param memberSummaryTree the content tree to which the documentation will be added
 */
 protected void buildAnnotationTypeRequiredMemberSummary(Content memberSummaryTree) {
-MemberSummaryWriter writer =
+MemberSummaryWriter writer = memberSummaryWriters.get(ANNOTATION_TYPE_MEMBER_REQUIRED);
-memberSummaryWriters.get(VisibleMemberMap.Kind.ANNOTATION_TYPE_MEMBER_REQUIRED);
+addSummary(writer, ANNOTATION_TYPE_MEMBER_REQUIRED, false, memberSummaryTree);
-VisibleMemberMap visibleMemberMap =
-getVisibleMemberMap(VisibleMemberMap.Kind.ANNOTATION_TYPE_MEMBER_REQUIRED);
-addSummary(writer, visibleMemberMap, false, memberSummaryTree);
 }
 /**
 * Build the summary for the fields.
 *
 * @param memberSummaryTree the content tree to which the documentation will be added
 */
 protected void buildFieldsSummary(Content memberSummaryTree) {
-MemberSummaryWriter writer =
+MemberSummaryWriter writer = memberSummaryWriters.get(FIELDS);
-memberSummaryWriters.get(VisibleMemberMap.Kind.FIELDS);
+addSummary(writer, FIELDS, true, memberSummaryTree);
-VisibleMemberMap visibleMemberMap =
-getVisibleMemberMap(VisibleMemberMap.Kind.FIELDS);
-addSummary(writer, visibleMemberMap, true, memberSummaryTree);
 }
 /**
 * Build the summary for the fields.
 *
 * @param memberSummaryTree the content tree to which the documentation will be added
 */
 protected void buildPropertiesSummary(Content memberSummaryTree) {
-MemberSummaryWriter writer =
+MemberSummaryWriter writer = memberSummaryWriters.get(PROPERTIES);
-memberSummaryWriters.get(VisibleMemberMap.Kind.PROPERTIES);
+addSummary(writer, PROPERTIES, true, memberSummaryTree);
-VisibleMemberMap visibleMemberMap =
-getVisibleMemberMap(VisibleMemberMap.Kind.PROPERTIES);
-addSummary(writer, visibleMemberMap, true, memberSummaryTree);
 }
 /**
 * Build the summary for the nested classes.
 *
 * @param memberSummaryTree the content tree to which the documentation will be added
 */
 protected void buildNestedClassesSummary(Content memberSummaryTree) {
-MemberSummaryWriter writer =
+MemberSummaryWriter writer = memberSummaryWriters.get(INNER_CLASSES);
-memberSummaryWriters.get(VisibleMemberMap.Kind.INNER_CLASSES);
+addSummary(writer, INNER_CLASSES, true, memberSummaryTree);
-VisibleMemberMap visibleMemberMap =
-getVisibleMemberMap(VisibleMemberMap.Kind.INNER_CLASSES);
-addSummary(writer, visibleMemberMap, true, memberSummaryTree);
 }
 /**
 * Build the method summary.
 *
 * @param memberSummaryTree the content tree to which the documentation will be added
 */
 protected void buildMethodsSummary(Content memberSummaryTree) {
-MemberSummaryWriter writer =
+MemberSummaryWriter writer = memberSummaryWriters.get(METHODS);
-memberSummaryWriters.get(VisibleMemberMap.Kind.METHODS);
+addSummary(writer, METHODS, true, memberSummaryTree);
-VisibleMemberMap visibleMemberMap =
-getVisibleMemberMap(VisibleMemberMap.Kind.METHODS);
-addSummary(writer, visibleMemberMap, true, memberSummaryTree);
 }
 /**
 * Build the constructor summary.
 *
 * @param memberSummaryTree the content tree to which the documentation will be added
 */
 protected void buildConstructorsSummary(Content memberSummaryTree) {
-MemberSummaryWriter writer =
+MemberSummaryWriter writer = memberSummaryWriters.get(CONSTRUCTORS);
-memberSummaryWriters.get(VisibleMemberMap.Kind.CONSTRUCTORS);
+addSummary(writer, CONSTRUCTORS, false, memberSummaryTree);
-VisibleMemberMap visibleMemberMap =
-getVisibleMemberMap(VisibleMemberMap.Kind.CONSTRUCTORS);
-addSummary(writer, visibleMemberMap, false, memberSummaryTree);
 }
 /**
 * Build the member summary for the given members.
 *
 * @param writer the summary writer to write the output.
-* @param visibleMemberMap the given members to summarize.
+* @param kind the kind of  members to summarize.
 * @param summaryTreeList list of content trees to which the documentation will be added
 */
 private void buildSummary(MemberSummaryWriter writer,
-VisibleMemberMap visibleMemberMap, LinkedList<Content> summaryTreeList) {
+VisibleMemberTable.Kind kind, LinkedList<Content> summaryTreeList) {
-SortedSet<Element> members = asSortedSet(visibleMemberMap.getLeafMembers());
+SortedSet<? extends Element> members = asSortedSet(getVisibleMembers(kind));
 if (!members.isEmpty()) {
 for (Element member : members) {
-final Element property = visibleMemberMap.getPropertyElement(member);
+final Element property = pHelper.getPropertyElement(member);
 if (property != null) {
-processProperty(visibleMemberMap, member, property);
+processProperty(member, property);
 }
 List<? extends DocTree> firstSentenceTags = utils.getFirstSentenceTrees(member);
 if (utils.isExecutableElement(member) && firstSentenceTags.isEmpty()) {
 //Inherit comments from overriden or implemented method if
 //necessary.
 * the property field. The method adds the leading sentence,
 * copied documentation including the defaultValue tag and
 * the see tags if the appropriate property getter and setter are
 * available.
 *
-* @param visibleMemberMap the members information.
 * @param member the member which is to be augmented.
 * @param property the original property documentation.
 */
-private void processProperty(VisibleMemberMap visibleMemberMap,
+private void processProperty(Element member,
-Element member,
 Element property) {
 CommentUtils cmtutils = configuration.cmtUtils;
 final boolean isSetter = isSetter(member);
 final boolean isGetter = isGetter(member);
 }
 }
 //add @see tags
 if (!isGetter && !isSetter) {
-ExecutableElement getter = (ExecutableElement) visibleMemberMap.getGetterForProperty(member);
+ExecutableElement getter = pHelper.getGetterForProperty((ExecutableElement)member);
-ExecutableElement setter = (ExecutableElement) visibleMemberMap.getSetterForProperty(member);
+ExecutableElement setter = pHelper.getSetterForProperty((ExecutableElement)member);
 if (null != getter) {
 StringBuilder sb = new StringBuilder("#");
 sb.append(utils.getSimpleName(getter)).append("()");
 blockTags.add(cmtutils.makeSeeTree(sb.toString(), getter));
 /**
 * Build the inherited member summary for the given methods.
 *
 * @param writer the writer for this member summary.
-* @param visibleMemberMap the map for the members to document.
+* @param kind the kind of members to document.
 * @param summaryTreeList list of content trees to which the documentation will be added
 */
 private void buildInheritedSummary(MemberSummaryWriter writer,
-VisibleMemberMap visibleMemberMap, LinkedList<Content> summaryTreeList) {
+VisibleMemberTable.Kind kind, LinkedList<Content> summaryTreeList) {
-for (TypeElement inheritedClass : visibleMemberMap.getVisibleClasses()) {
+VisibleMemberTable visibleMemberTable = getVisibleMemberTable();
+SortedSet<? extends Element> inheritedMembersFromMap = asSortedSet(visibleMemberTable.getAllVisibleMembers(kind));
+for (TypeElement inheritedClass : visibleMemberTable.getVisibleTypeElements()) {
 if (!(utils.isPublic(inheritedClass) || utils.isLinkable(inheritedClass))) {
 continue;
 }
 if (inheritedClass == typeElement) {
 continue;
 }
-SortedSet<Element> inheritedMembersFromMap = asSortedSet(
-visibleMemberMap.getMembers(inheritedClass));
+List<Element> members = inheritedMembersFromMap.stream()
+.filter(e -> utils.getEnclosingTypeElement(e) == inheritedClass)
-if (!inheritedMembersFromMap.isEmpty()) {
+.collect(Collectors.toList());
+if (!members.isEmpty()) {
 SortedSet<Element> inheritedMembers = new TreeSet<>(comparator);
-List<ExecutableElement> enclosedSuperMethods = utils.getMethods(inheritedClass);
+inheritedMembers.addAll(members);
-for (Element inheritedMember : inheritedMembersFromMap) {
-if (visibleMemberMap.kind != VisibleMemberMap.Kind.METHODS) {
-inheritedMembers.add(inheritedMember);
-continue;
-}
-// Skip static methods in interfaces they are not inherited
-if (utils.isInterface(inheritedClass) && utils.isStatic(inheritedMember))
-continue;
-// If applicable, filter those overridden methods that
-// should not be documented in the summary/detail sections,
-// and instead document them in the footnote. Care must be taken
-// to handle JavaFX property methods, which have no source comments,
-// but comments for these are synthesized on the output.
-ExecutableElement inheritedMethod = (ExecutableElement)inheritedMember;
-if (enclosedSuperMethods.stream()
-.anyMatch(e -> utils.executableMembersEqual(inheritedMethod, e) &&
-(!utils.isSimpleOverride(e) || visibleMemberMap.getPropertyElement(e) != null))) {
-inheritedMembers.add(inheritedMember);
-}
-}
 Content inheritedTree = writer.getInheritedSummaryHeader(inheritedClass);
 Content linksTree = writer.getInheritedSummaryLinksTree();
 addSummaryFootNote(inheritedClass, inheritedMembers, linksTree, writer);
 inheritedTree.addContent(linksTree);
 summaryTreeList.add(writer.getMemberTree(inheritedTree));
 /**
 * Add the summary for the documentation.
 *
 * @param writer the writer for this member summary.
-* @param visibleMemberMap the map for the members to document.
+* @param kind the kind of members to document.
 * @param showInheritedSummary true if inherited summary should be documented
 * @param memberSummaryTree the content tree to which the documentation will be added
 */
 private void addSummary(MemberSummaryWriter writer,
-VisibleMemberMap visibleMemberMap, boolean showInheritedSummary,
+VisibleMemberTable.Kind kind, boolean showInheritedSummary,
 Content memberSummaryTree) {
 LinkedList<Content> summaryTreeList = new LinkedList<>();
-buildSummary(writer, visibleMemberMap, summaryTreeList);
+buildSummary(writer, kind, summaryTreeList);
 if (showInheritedSummary)
-buildInheritedSummary(writer, visibleMemberMap, summaryTreeList);
+buildInheritedSummary(writer, kind, summaryTreeList);
 if (!summaryTreeList.isEmpty()) {
 Content memberTree = writer.getMemberSummaryHeader(typeElement, memberSummaryTree);
 summaryTreeList.stream().forEach(memberTree::addContent);
 writer.addMemberTree(memberSummaryTree, memberTree);
 }
 }
-private SortedSet<Element> asSortedSet(Collection<Element> members) {
+private SortedSet<? extends Element> asSortedSet(Collection<? extends Element> members) {
 SortedSet<Element> out = new TreeSet<>(comparator);
 out.addAll(members);
 return out;
 }
+static class PropertyHelper {
+private final Map<Element, Element> classPropertiesMap = new HashMap<>();
+private final MemberSummaryBuilder  builder;
+PropertyHelper(MemberSummaryBuilder builder) {
+this.builder = builder;
+computeProperties();
+}
+private void computeProperties() {
+VisibleMemberTable vmt = builder.getVisibleMemberTable();
+List<ExecutableElement> props = ElementFilter.methodsIn(vmt.getVisibleMembers(PROPERTIES));
+for (ExecutableElement propertyMethod : props) {
+ExecutableElement getter = vmt.getPropertyGetter(propertyMethod);
+ExecutableElement setter = vmt.getPropertySetter(propertyMethod);
+VariableElement field = vmt.getPropertyField(propertyMethod);
+addToPropertiesMap(propertyMethod, field, getter, setter);
+}
+}
+private void addToPropertiesMap(ExecutableElement propertyMethod,
+VariableElement field,
+ExecutableElement getter,
+ExecutableElement setter) {
+if (field == null || builder.utils.getDocCommentTree(field) == null) {
+addToPropertiesMap(propertyMethod, propertyMethod);
+addToPropertiesMap(getter, propertyMethod);
+addToPropertiesMap(setter, propertyMethod);
+} else {
+addToPropertiesMap(propertyMethod, field);
+addToPropertiesMap(getter, field);
+addToPropertiesMap(setter, field);
+}
+}
+private void addToPropertiesMap(Element propertyMethod,
+Element commentSource) {
+if (null == propertyMethod || null == commentSource) {
+return;
+}
+DocCommentTree docTree = builder.utils.getDocCommentTree(propertyMethod);
+/* The second condition is required for the property buckets. In
+* this case the comment is at the property method (not at the field)
+* and it needs to be listed in the map.
+*/
+if ((docTree == null) || propertyMethod.equals(commentSource)) {
+classPropertiesMap.put(propertyMethod, commentSource);
+}
+}
+/**
+* Returns the property field documentation belonging to the given member.
+* @param element the member for which the property documentation is needed.
+* @return the property field documentation, null if there is none.
+*/
+public Element getPropertyElement(Element element) {
+return classPropertiesMap.get(element);
+}
+/**
+* Returns the getter documentation belonging to the given property method.
+* @param propertyMethod the method for which the getter is needed.
+* @return the getter documentation, null if there is none.
+*/
+public ExecutableElement getGetterForProperty(ExecutableElement propertyMethod) {
+return builder.getVisibleMemberTable().getPropertyGetter(propertyMethod);
+}
+/**
+* Returns the setter documentation belonging to the given property method.
+* @param propertyMethod the method for which the setter is needed.
+* @return the setter documentation, null if there is none.
+*/
+public ExecutableElement getSetterForProperty(ExecutableElement propertyMethod) {
+return builder.getVisibleMemberTable().getPropertySetter(propertyMethod);
+}
+}
 }

changeset 49879	601277b1d582
parent 48257	125716343184
child 52644	43efb4ca6d6c