/**
   * 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;
  }
Exemple #2
0
 /**
  * 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;
 }
 /** {@inheritDoc} */
 public Content getTagletOutput(Tag tag, TagletWriter writer) {
   ArrayList inlineTags = new ArrayList();
   inlineTags.add(new TextTag(tag.holder(), "<b>"));
   inlineTags.addAll(Arrays.asList(tag.inlineTags()));
   inlineTags.add(new TextTag(tag.holder(), "</b>"));
   return writer.commentTagsToOutput(tag, (Tag[]) inlineTags.toArray(new Tag[] {}));
 }
Exemple #4
0
 /** 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;
 }
Exemple #5
0
 /**
  * Convert the individual ParamTag into TagletOutput.
  *
  * @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 TagletOutput processParamTag(
     boolean isNonTypeParams,
     TagletWriter writer,
     ParamTag paramTag,
     String name,
     boolean isFirstParam) {
   TagletOutput result = writer.getOutputInstance();
   String header =
       writer
           .configuration()
           .getText(isNonTypeParams ? "doclet.Parameters" : "doclet.TypeParameters");
   if (isFirstParam) {
     result.appendOutput(writer.getParamHeader(header));
   }
   result.appendOutput(writer.paramTagOutput(paramTag, name));
   return result;
 }
Exemple #6
0
 /** Add links for exceptions that are declared but not documented. */
 private TagletOutput linkToUndocumentedDeclaredExceptions(
     Type[] declaredExceptionTypes, Set<String> alreadyDocumented, TagletWriter writer) {
   TagletOutput result = writer.getOutputInstance();
   // Add links to the exceptions declared but not documented.
   for (int i = 0; i < declaredExceptionTypes.length; i++) {
     if (declaredExceptionTypes[i].asClassDoc() != null
         && !alreadyDocumented.contains(declaredExceptionTypes[i].asClassDoc().name())
         && !alreadyDocumented.contains(declaredExceptionTypes[i].asClassDoc().qualifiedName())) {
       if (alreadyDocumented.size() == 0) {
         result.appendOutput(writer.getThrowsHeader());
       }
       result.appendOutput(writer.throwsTagOutput(declaredExceptionTypes[i]));
       alreadyDocumented.add(declaredExceptionTypes[i].asClassDoc().name());
     }
   }
   return result;
 }
 /**
  * Given the <code>Tag</code> representation of this custom tag, return its string representation,
  * which is output to the generated page.
  *
  * @param tag the <code>Tag</code> representation of this custom tag.
  * @param tagletWriter the taglet writer for output.
  * @return the TagletOutput representation of this <code>Tag</code>.
  */
 public TagletOutput getTagletOutput(Tag tag, TagletWriter tagletWriter) {
   if (!(tag.holder() instanceof MethodDoc)) {
     return tagletWriter.getOutputInstance();
   }
   return tag.name().equals("@inheritDoc")
       ? retrieveInheritedDocumentation(
           tagletWriter, (MethodDoc) tag.holder(), null, tagletWriter.isFirstSentence)
       : retrieveInheritedDocumentation(
           tagletWriter, (MethodDoc) tag.holder(), tag, tagletWriter.isFirstSentence);
 }
Exemple #8
0
 /**
  * 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 nameMap 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 TagletOutput representation of this <code>Tag</code>.
  */
 private TagletOutput processParamTags(
     boolean isNonTypeParams,
     ParamTag[] paramTags,
     Map rankMap,
     TagletWriter writer,
     Set alreadyDocumented) {
   TagletOutput result = writer.getOutputInstance();
   if (paramTags.length > 0) {
     for (int i = 0; i < paramTags.length; ++i) {
       ParamTag pt = paramTags[i];
       String paramName = isNonTypeParams ? pt.parameterName() : "<" + pt.parameterName() + ">";
       if (!rankMap.containsKey(pt.parameterName())) {
         writer
             .getMsgRetriever()
             .warning(
                 pt.position(),
                 isNonTypeParams ? "doclet.Parameters_warn" : "doclet.Type_Parameters_warn",
                 paramName);
       }
       String rank = (String) rankMap.get(pt.parameterName());
       if (rank != null && alreadyDocumented.contains(rank)) {
         writer
             .getMsgRetriever()
             .warning(
                 pt.position(),
                 isNonTypeParams
                     ? "doclet.Parameters_dup_warn"
                     : "doclet.Type_Parameters_dup_warn",
                 paramName);
       }
       result.appendOutput(
           processParamTag(
               isNonTypeParams, writer, pt, pt.parameterName(), alreadyDocumented.size() == 0));
       alreadyDocumented.add(rank);
     }
   }
   return result;
 }
Exemple #9
0
 /**
  * Given an array of <code>Tag</code>s representing this custom tag, return its string
  * representation.
  *
  * @param throwTags the array of <code>ThrowsTag</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 allowDups True if we allow duplicate throws tags to be documented.
  * @return the TagletOutput representation of this <code>Tag</code>.
  */
 protected TagletOutput throwsTagsOutput(
     ThrowsTag[] throwTags,
     TagletWriter writer,
     Set<String> alreadyDocumented,
     boolean allowDups) {
   TagletOutput result = writer.getOutputInstance();
   if (throwTags.length > 0) {
     for (int i = 0; i < throwTags.length; ++i) {
       ThrowsTag tt = throwTags[i];
       ClassDoc cd = tt.exception();
       if ((!allowDups)
           && (alreadyDocumented.contains(tt.exceptionName())
               || (cd != null && alreadyDocumented.contains(cd.qualifiedName())))) {
         continue;
       }
       if (alreadyDocumented.size() == 0) {
         result.appendOutput(writer.getThrowsHeader());
       }
       result.appendOutput(writer.throwsTagOutput(tt));
       alreadyDocumented.add(cd != null ? cd.qualifiedName() : tt.exceptionName());
     }
   }
   return result;
 }
Exemple #10
0
 /** {@inheritDoc} */
 public TagletOutput getTagletOutput(Doc holder, TagletWriter writer) {
   ExecutableMemberDoc execHolder = (ExecutableMemberDoc) holder;
   ThrowsTag[] tags = execHolder.throwsTags();
   TagletOutput result = writer.getOutputInstance();
   HashSet<String> alreadyDocumented = new HashSet<String>();
   if (tags.length > 0) {
     result.appendOutput(
         throwsTagsOutput(execHolder.throwsTags(), writer, alreadyDocumented, true));
   }
   result.appendOutput(
       inheritThrowsDocumentation(
           holder, execHolder.thrownExceptionTypes(), alreadyDocumented, writer));
   result.appendOutput(
       linkToUndocumentedDeclaredExceptions(
           execHolder.thrownExceptionTypes(), alreadyDocumented, writer));
   return result;
 }
Exemple #11
0
 /**
  * Given an array of <code>ParamTag</code>s,return its string representation. Try to inherit the
  * param tags that are missing.
  *
  * @param doc the doc 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 TagletOutput getTagletOutput(
     boolean isNonTypeParams,
     Doc holder,
     TagletWriter writer,
     Object[] formalParameters,
     ParamTag[] paramTags) {
   TagletOutput result = writer.getOutputInstance();
   Set alreadyDocumented = new HashSet();
   if (paramTags.length > 0) {
     result.appendOutput(
         processParamTags(
             isNonTypeParams, paramTags, getRankMap(formalParameters), writer, alreadyDocumented));
   }
   if (alreadyDocumented.size() != formalParameters.length) {
     // Some parameters are missing corresponding @param tags.
     // Try to inherit them.
     result.appendOutput(
         getInheritedTagletOutput(
             isNonTypeParams, holder, writer, formalParameters, alreadyDocumented));
   }
   return result;
 }