< prev index next >
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/ParamTaglet.java
Print this page
rev 58565 : records: mark record related model API as preview
*** 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. */
+ RECORD_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;
}
}
}
*** 126,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)) {
--- 135,199 ----
}
}
}
@Override
+ @SuppressWarnings("preview")
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.RECORD_COMPONENT, typeElement, writer,
+ typeElement.getRecordComponents(), 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);
}
--- 202,221 ----
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;
}
--- 241,317 ----
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 RECORD_COMPONENT: key = "doclet.RecordComponents_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 RECORD_COMPONENT: key = "doclet.RecordComponents_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 RECORD_COMPONENT: key = "doclet.RecordComponents" ; 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 >