Example #1
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;
 }
Example #2
0
  /**
   * 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;
  }
Example #3
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;
 }
  /**
   * 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);
    }
  }