< prev index next >

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/ParamTaglet.java

Print this page

        

@@ -27,10 +27,11 @@
 
 import java.util.*;
 
 import javax.lang.model.element.Element;
 import javax.lang.model.element.ExecutableElement;
+import javax.lang.model.element.Name;
 import javax.lang.model.element.TypeElement;
 
 import com.sun.source.doctree.DocTree;
 import com.sun.source.doctree.ParamTree;
 import jdk.javadoc.internal.doclets.toolkit.Content;

@@ -51,10 +52,18 @@
  *  deletion without notice.</b>
  *
  * @author Jamie Ho
  */
 public class ParamTaglet extends BaseTaglet implements InheritableTaglet {
+    private enum ParamKind {
+        /** Parameter of an executable element. */
+        PARAMETER,
+        /** State components of a record. */
+        STATE_COMPONENT,
+        /** Type parameters of an executable element or type element. */
+        TYPE_PARAMETER
+    }
 
     /**
      * Construct a ParamTaglet.
      */
     public ParamTaglet() {

@@ -99,11 +108,11 @@
             for (int i = 0 ; i < parameters.size(); i++) {
                 Element e = parameters.get(i);
                 String pname = input.isTypeVariableParamTag
                         ? utils.getTypeName(e.asType(), false)
                         : utils.getSimpleName(e);
-                if (pname.equals(target)) {
+                if (pname.contentEquals(target)) {
                     input.tagId = String.valueOf(i);
                     break;
                 }
             }
         }

@@ -130,57 +139,60 @@
     @Override
     public Content getTagletOutput(Element holder, TagletWriter writer) {
         Utils utils = writer.configuration().utils;
         if (utils.isExecutableElement(holder)) {
             ExecutableElement member = (ExecutableElement) holder;
-            Content output = getTagletOutput(false, member, writer,
+            Content output = getTagletOutput(ParamKind.TYPE_PARAMETER, member, writer,
                 member.getTypeParameters(), utils.getTypeParamTrees(member));
-            output.add(getTagletOutput(true, member, writer,
+            output.add(getTagletOutput(ParamKind.PARAMETER, member, writer,
                 member.getParameters(), utils.getParamTrees(member)));
             return output;
         } else {
             TypeElement typeElement = (TypeElement) holder;
-            return getTagletOutput(false, typeElement, writer,
+            Content output = getTagletOutput(ParamKind.TYPE_PARAMETER, typeElement, writer,
                 typeElement.getTypeParameters(), utils.getTypeParamTrees(typeElement));
+            output.add(getTagletOutput(ParamKind.STATE_COMPONENT, typeElement, writer,
+                    typeElement.getStateComponents(), utils.getParamTrees(typeElement)));
+            return output;
         }
     }
 
     /**
      * Given an array of {@code @param DocTree}s,return its string representation.
      * Try to inherit the param tags that are missing.
      *
      * @param holder            the element that holds the param tags.
      * @param writer            the TagletWriter that will write this tag.
-     * @param formalParameters  The array of parmeters (from type or executable
+     * @param formalParameters  The array of parameters (from type or executable
      *                          member) to check.
      *
      * @return the content representation of these {@code @param DocTree}s.
      */
-    private Content getTagletOutput(boolean isParameters, Element holder,
+    private Content getTagletOutput(ParamKind kind, Element holder,
             TagletWriter writer, List<? extends Element> formalParameters, List<? extends DocTree> paramTags) {
         Content result = writer.getOutputInstance();
         Set<String> alreadyDocumented = new HashSet<>();
         if (!paramTags.isEmpty()) {
             result.add(
-                processParamTags(holder, isParameters, paramTags,
+                processParamTags(holder, kind, paramTags,
                 getRankMap(writer.configuration().utils, formalParameters), writer, alreadyDocumented)
             );
         }
         if (alreadyDocumented.size() != formalParameters.size()) {
             //Some parameters are missing corresponding @param tags.
             //Try to inherit them.
-            result.add(getInheritedTagletOutput(isParameters, holder,
+            result.add(getInheritedTagletOutput(kind, holder,
                 writer, formalParameters, alreadyDocumented));
         }
         return result;
     }
 
     /**
      * Loop through each individual parameter, despite not having a
      * corresponding param tag, try to inherit it.
      */
-    private Content getInheritedTagletOutput(boolean isParameters, Element holder,
+    private Content getInheritedTagletOutput(ParamKind kind, Element holder,
             TagletWriter writer, List<? extends Element> formalParameters,
             Set<String> alreadyDocumented) {
         Utils utils = writer.configuration().utils;
         Content result = writer.getOutputInstance();
         if ((!alreadyDocumented.contains(null)) && utils.isExecutableElement(holder)) {

@@ -189,20 +201,20 @@
                     continue;
                 }
                 // This parameter does not have any @param documentation.
                 // Try to inherit it.
                 Input input = new DocFinder.Input(writer.configuration().utils, holder, this,
-                        Integer.toString(i), !isParameters);
+                        Integer.toString(i), kind == ParamKind.TYPE_PARAMETER);
                 DocFinder.Output inheritedDoc = DocFinder.search(writer.configuration(), input);
                 if (inheritedDoc.inlineTags != null && !inheritedDoc.inlineTags.isEmpty()) {
                     Element e = formalParameters.get(i);
-                    String lname = isParameters
+                    String lname = kind != ParamKind.TYPE_PARAMETER
                             ? utils.getSimpleName(e)
                             : utils.getTypeName(e.asType(), false);
                     CommentHelper ch = utils.getCommentHelper(holder);
                     ch.setOverrideElement(inheritedDoc.holder);
-                    Content content = processParamTag(holder, isParameters, writer,
+                    Content content = processParamTag(holder, kind, writer,
                             inheritedDoc.holderTag,
                             lname,
                             alreadyDocumented.isEmpty());
                     result.add(content);
                 }

@@ -228,65 +240,77 @@
                 of a rank of a parameter to its name.  This is
                 used to ensure that the right name is used
                 when parameter documentation is inherited.
      * @return the Content representation of this {@code @param DocTree}.
      */
-    private Content processParamTags(Element e, boolean isParams,
+    private Content processParamTags(Element e, ParamKind kind,
             List<? extends DocTree> paramTags, Map<String, String> rankMap, TagletWriter writer,
             Set<String> alreadyDocumented) {
         Messages messages = writer.configuration().getMessages();
         Content result = writer.getOutputInstance();
         if (!paramTags.isEmpty()) {
             CommentHelper ch = writer.configuration().utils.getCommentHelper(e);
             for (DocTree dt : paramTags) {
-                String paramName = isParams
-                        ? ch.getParameterName(dt)
-                        : "<" + ch.getParameterName(dt) + ">";
-                if (!rankMap.containsKey(ch.getParameterName(dt))) {
-                    messages.warning(ch.getDocTreePath(dt),
-                            isParams
-                                    ? "doclet.Parameters_warn"
-                                    : "doclet.Type_Parameters_warn",
-                            paramName);
+                String name = ch.getParameterName(dt);
+                String paramName = kind != ParamKind.TYPE_PARAMETER
+                        ? name.toString()
+                        : "<" + name + ">";
+                if (!rankMap.containsKey(name)) {
+                    String key;
+                    switch (kind) {
+                        case PARAMETER:       key = "doclet.Parameters_warn" ; break;
+                        case TYPE_PARAMETER:  key = "doclet.TypeParameters_warn" ; break;
+                        case STATE_COMPONENT: key = "doclet.StateComponents_warn" ; break;
+                        default: throw new IllegalArgumentException(kind.toString());
+                    }
+                    messages.warning(ch.getDocTreePath(dt), key, paramName);
                 }
-                String rank = rankMap.get(ch.getParameterName(dt));
+                String rank = rankMap.get(name);
                 if (rank != null && alreadyDocumented.contains(rank)) {
-                    messages.warning(ch.getDocTreePath(dt),
-                            isParams
-                                    ? "doclet.Parameters_dup_warn"
-                                    : "doclet.Type_Parameters_dup_warn",
-                            paramName);
+                    String key;
+                    switch (kind) {
+                        case PARAMETER:       key = "doclet.Parameters_dup_warn" ; break;
+                        case TYPE_PARAMETER:  key = "doclet.TypeParameters_dup_warn" ; break;
+                        case STATE_COMPONENT: key = "doclet.StateComponents_dup_warn" ; break;
+                        default: throw new IllegalArgumentException(kind.toString());
+                    }
+                    messages.warning(ch.getDocTreePath(dt), key, paramName);
                 }
-                result.add(processParamTag(e, isParams, writer, dt,
-                        ch.getParameterName(dt), alreadyDocumented.isEmpty()));
+                result.add(processParamTag(e, kind, writer, dt,
+                        name, alreadyDocumented.isEmpty()));
                 alreadyDocumented.add(rank);
             }
         }
         return result;
     }
 
     /**
      * Convert the individual ParamTag into Content.
      *
      * @param e               the owner element
-     * @param isParams true   if this is just a regular param tag.  False
-     *                        if this is a type param tag.
+     * @param kind            the kind of param tag
      * @param writer          the taglet writer for output writing.
      * @param paramTag        the tag whose inline tags will be printed.
      * @param name            the name of the parameter.  We can't rely on
      *                        the name in the param tag because we might be
      *                        inheriting documentation.
      * @param isFirstParam    true if this is the first param tag being printed.
      *
      */
-    private Content processParamTag(Element e, boolean isParams,
+    private Content processParamTag(Element e, ParamKind kind,
             TagletWriter writer, DocTree paramTag, String name,
             boolean isFirstParam) {
         Content result = writer.getOutputInstance();
-        String header = writer.configuration().getResources().getText(
-            isParams ? "doclet.Parameters" : "doclet.TypeParameters");
         if (isFirstParam) {
+            String key;
+            switch (kind) {
+                case PARAMETER:       key = "doclet.Parameters" ; break;
+                case TYPE_PARAMETER:  key = "doclet.TypeParameters" ; break;
+                case STATE_COMPONENT: key = "doclet.StateComponents" ; break;
+                default: throw new IllegalArgumentException(kind.toString());
+            }
+            String header = writer.configuration().getResources().getText(key);
             result.add(writer.getParamHeader(header));
         }
         result.add(writer.paramTagOutput(e, paramTag, name));
         return result;
     }
< prev index next >