Exemplo n.º 1
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 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;
 }
Exemplo n.º 2
0
 /**
  * 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;
 }
Exemplo n.º 3
0
 /**
  * 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;
 }
Exemplo n.º 4
0
 /**
  * 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;
 }
Exemplo n.º 5
0
 /**
  * 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));
   }
 }