< prev index next >

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

Print this page

        

*** 27,36 **** --- 27,37 ---- 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,60 **** --- 52,69 ---- * 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,109 **** 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)) { input.tagId = String.valueOf(i); break; } } } --- 108,118 ---- 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.contentEquals(target)) { input.tagId = String.valueOf(i); break; } } }
*** 130,186 **** @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, member.getTypeParameters(), utils.getTypeParamTrees(member)); ! output.add(getTagletOutput(true, member, writer, member.getParameters(), utils.getParamTrees(member))); return output; } else { TypeElement typeElement = (TypeElement) holder; ! return getTagletOutput(false, typeElement, writer, typeElement.getTypeParameters(), utils.getTypeParamTrees(typeElement)); } } /** * 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 * member) to check. * * @return the content representation of these {@code @param DocTree}s. */ ! private Content getTagletOutput(boolean isParameters, 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, 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, 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, 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)) { --- 139,198 ---- @Override public Content getTagletOutput(Element holder, TagletWriter writer) { Utils utils = writer.configuration().utils; if (utils.isExecutableElement(holder)) { ExecutableElement member = (ExecutableElement) holder; ! Content output = getTagletOutput(ParamKind.TYPE_PARAMETER, member, writer, member.getTypeParameters(), utils.getTypeParamTrees(member)); ! output.add(getTagletOutput(ParamKind.PARAMETER, member, writer, member.getParameters(), utils.getParamTrees(member))); return output; } else { TypeElement typeElement = (TypeElement) holder; ! 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 parameters (from type or executable * member) to check. * * @return the content representation of these {@code @param DocTree}s. */ ! 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, 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(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(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,208 **** 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); DocFinder.Output inheritedDoc = DocFinder.search(writer.configuration(), input); if (inheritedDoc.inlineTags != null && !inheritedDoc.inlineTags.isEmpty()) { Element e = formalParameters.get(i); ! String lname = isParameters ? utils.getSimpleName(e) : utils.getTypeName(e.asType(), false); CommentHelper ch = utils.getCommentHelper(holder); ch.setOverrideElement(inheritedDoc.holder); ! Content content = processParamTag(holder, isParameters, writer, inheritedDoc.holderTag, lname, alreadyDocumented.isEmpty()); result.add(content); } --- 201,220 ---- 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), 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 = 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, kind, writer, inheritedDoc.holderTag, lname, alreadyDocumented.isEmpty()); result.add(content); }
*** 228,292 **** 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, 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 rank = rankMap.get(ch.getParameterName(dt)); if (rank != null && alreadyDocumented.contains(rank)) { ! messages.warning(ch.getDocTreePath(dt), ! isParams ! ? "doclet.Parameters_dup_warn" ! : "doclet.Type_Parameters_dup_warn", ! paramName); } ! result.add(processParamTag(e, isParams, writer, dt, ! ch.getParameterName(dt), 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 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, 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) { result.add(writer.getParamHeader(header)); } result.add(writer.paramTagOutput(e, paramTag, name)); return result; } --- 240,316 ---- 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, 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 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(name); if (rank != null && alreadyDocumented.contains(rank)) { ! 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, kind, writer, dt, ! name, alreadyDocumented.isEmpty())); alreadyDocumented.add(rank); } } return result; } /** * Convert the individual ParamTag into Content. * * @param e the owner element ! * @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, ParamKind kind, TagletWriter writer, DocTree paramTag, String name, boolean isFirstParam) { Content result = writer.getOutputInstance(); 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 >