/** 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); } }