/** Inherit throws documentation for exceptions that were declared but not documented. */
private TagletOutput inheritThrowsDocumentation(
Doc holder,
Type[] declaredExceptionTypes,
Set<String> alreadyDocumented,
TagletWriter writer) {
TagletOutput result = writer.getOutputInstance();
if (holder instanceof MethodDoc) {
Set<Tag> declaredExceptionTags = new LinkedHashSet<Tag>();
for (int j = 0; j < declaredExceptionTypes.length; j++) {
DocFinder.Output inheritedDoc =
DocFinder.search(
new DocFinder.Input(
(MethodDoc) holder, this, declaredExceptionTypes[j].typeName()));
if (inheritedDoc.tagList.size() == 0) {
inheritedDoc =
DocFinder.search(
new DocFinder.Input(
(MethodDoc) holder, this, declaredExceptionTypes[j].qualifiedTypeName()));
}
declaredExceptionTags.addAll(inheritedDoc.tagList);
}
result.appendOutput(
throwsTagsOutput(
declaredExceptionTags.toArray(new ThrowsTag[] {}), writer, alreadyDocumented, false));
}
return result;
}
/**
* Given a <code>MethodDoc</code> item, a <code>Tag</code> in the <code>MethodDoc</code> item and
* a String, replace all occurrences of @inheritDoc with documentation from it's superclass or
* superinterface.
*
* @param writer the writer that is writing the output.
* @param md the {@link MethodDoc} that we are documenting.
* @param holderTag the tag that holds the inheritDoc tag.
* @param isFirstSentence true if we only want to inherit the first sentence.
*/
private TagletOutput retrieveInheritedDocumentation(
TagletWriter writer, MethodDoc md, Tag holderTag, boolean isFirstSentence) {
TagletOutput replacement = writer.getTagletOutputInstance();
Configuration configuration = writer.configuration();
Taglet inheritableTaglet =
holderTag == null ? null : configuration.tagletManager.getTaglet(holderTag.name());
if (inheritableTaglet != null && !(inheritableTaglet instanceof InheritableTaglet)) {
// This tag does not support inheritence.
configuration.message.warning(
md.position(), "doclet.noInheritedDoc", md.name() + md.flatSignature());
}
DocFinder.Output inheritedDoc =
DocFinder.search(
new DocFinder.Input(
md, (InheritableTaglet) inheritableTaglet, holderTag, isFirstSentence, true));
if (inheritedDoc.isValidInheritDocTag == false) {
configuration.message.warning(
md.position(), "doclet.noInheritedDoc", md.name() + md.flatSignature());
} else if (inheritedDoc.inlineTags.length > 0) {
replacement =
writer.commentTagsToOutput(
inheritedDoc.holderTag,
inheritedDoc.holder,
inheritedDoc.inlineTags,
isFirstSentence);
}
return replacement;
}
/**
* Loop through each indivitual parameter. It it does not have a corresponding param tag, try to
* inherit it.
*/
private TagletOutput getInheritedTagletOutput(
boolean isNonTypeParams,
Doc holder,
TagletWriter writer,
Object[] formalParameters,
Set alreadyDocumented) {
TagletOutput result = writer.getOutputInstance();
if ((!alreadyDocumented.contains(null)) && holder instanceof MethodDoc) {
for (int i = 0; i < formalParameters.length; i++) {
if (alreadyDocumented.contains(String.valueOf(i))) {
continue;
}
// This parameter does not have any @param documentation.
// Try to inherit it.
DocFinder.Output inheritedDoc =
DocFinder.search(
new DocFinder.Input((MethodDoc) holder, this, String.valueOf(i), !isNonTypeParams));
if (inheritedDoc.inlineTags != null && inheritedDoc.inlineTags.length > 0) {
result.appendOutput(
processParamTag(
isNonTypeParams,
writer,
(ParamTag) inheritedDoc.holderTag,
isNonTypeParams
? ((Parameter) formalParameters[i]).name()
: ((TypeVariable) formalParameters[i]).typeName(),
alreadyDocumented.size() == 0));
}
alreadyDocumented.add(String.valueOf(i));
}
}
return result;
}
/**
* Build the comments for the method. Do nothing if {@link Configuration#nocomment} is set to
* true.
*
* @param node the XML element that specifies which components to document
* @param methodDocTree the content tree to which the documentation will be added
*/
public void buildMethodComments(XMLNode node, Content methodDocTree) {
if (!configuration.nocomment) {
MethodDoc method = (MethodDoc) methods.get(currentMethodIndex);
if (method.inlineTags().length == 0) {
DocFinder.Output docs = DocFinder.search(configuration, new DocFinder.Input(method));
method =
docs.inlineTags != null && docs.inlineTags.length > 0
? (MethodDoc) docs.holder
: method;
}
// NOTE: When we fix the bug where ClassDoc.interfaceTypes() does
// not pass all implemented interfaces, holder will be the
// interface type. For now, it is really the erasure.
writer.addComments(method.containingClass(), method, methodDocTree);
}
}
