/**
* Given an array of <code>Tag</code>s representing this custom tag, return its string
* representation. Print a warning for param tags that do not map to parameters. Print a warning
* for param tags that are duplicated.
*
* @param paramTags the array of <code>ParamTag</code>s to convert.
* @param writer the TagletWriter that will write this tag.
* @param alreadyDocumented the set of exceptions that have already been documented.
* @param rankMap a {@link java.util.Map} which holds ordering information about the parameters.
* @param rankMap a {@link java.util.Map} which holds a mapping 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>Tag</code>.
*/
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.addContent(
processParamTag(
e, isParams, writer, dt, ch.getParameterName(dt), alreadyDocumented.isEmpty()));
alreadyDocumented.add(rank);
}
}
return result;
}
/**
* Given an array of <code>ParamTag</code>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 TagletOutput representation of these <code>ParamTag</code>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.addContent(
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.addContent(
getInheritedTagletOutput(
isParameters, holder, writer, formalParameters, alreadyDocumented));
}
return result;
}
/**
* Convert the individual ParamTag into Content.
*
* @param isNonTypeParams 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().getText(isParams ? "doclet.Parameters" : "doclet.TypeParameters");
if (isFirstParam) {
result.addContent(writer.getParamHeader(header));
}
result.addContent(writer.paramTagOutput(e, paramTag, name));
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)) {
for (int i = 0; i < formalParameters.size(); i++) {
if (alreadyDocumented.contains(String.valueOf(i))) {
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.addContent(content);
}
alreadyDocumented.add(String.valueOf(i));
}
}
return result;
}
/**
* Given an array of <code>ParamTag</code>s,return its string representation.
*
* @param holder the member that holds the param tags.
* @param writer the TagletWriter that will write this tag.
* @return the TagletOutput representation of these <code>ParamTag</code>s.
*/
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.addContent(
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));
}
}