Java 类com.sun.javadoc.ParamTag 实例源码

@Override
public DocTag converter(ParamTag o) {

    //解析 "@param user :username 用户名|必填" 这种注释
    boolean require = false;
    String paramDesc = o.parameterComment();
    if (paramDesc.contains("|")) {
        int endIndex = paramDesc.lastIndexOf("|必填");
        require = endIndex > 0;
        if (require) {
            paramDesc = paramDesc.substring(0, endIndex);
        }
    }

    String paramName = StringUtils.defaultString(o.parameterName());
    if (paramDesc.startsWith(":")) {
        int index = paramDesc.indexOf(" ");
        if (index > 0) {
            paramName = paramDesc.substring(1, index);
            paramDesc = paramDesc.substring(index + 1);
        }
    }
    return new ParamTagImpl(o.name(), paramName, paramDesc, require);
}

/**
 * @return the first non-null ParamTag with the given parameterName in the inheritance tree
 *         for the given methodDoc.
 */
protected ParamTag getInheritedParamTag(MethodDoc methodDoc, String parameterName, MethodDoc specifiedByMethodDoc)  {

    for ( ;
         methodDoc != null;
         methodDoc = methodDoc.overriddenMethod() ) {

        ParamTag retMe = getParamTag( methodDoc.paramTags(), parameterName );
        if (retMe != null) {
            return retMe;
        }
    }

    // Couldn't find it in the superclass hierarchy. Check the interface method
    return (specifiedByMethodDoc != null) ? getParamTag( specifiedByMethodDoc.paramTags(), parameterName ) : null;
}

@Override
public String getParamDoc(Method method, String name)
{
  final MethodDoc methodDoc = Rest4JDoclet.getMethodDoc(_docletId, method);
  if (methodDoc != null)
  {
    for (ParamTag tag: methodDoc.paramTags())
    {
      if (name.equals(tag.parameterName()))
      {
        return buildDoc(tag.parameterComment());
      }
    }
  }

  return null;
}

/**
 * Renders a document tag in the standard way.
 *
 * @param tag input
 * @param buffer output buffer
 */
private void renderTag(Tag tag, StringBuilder buffer) {
    buffer.append(tag.name()).append(' ');
    // Special handling for @param <T> tags
    // See http://docs.oracle.com/javase/1.5.0/docs/tooldocs/windows/javadoc.html#@param
    if ((tag instanceof ParamTag) && ((ParamTag) tag).isTypeParameter()) {
        ParamTag paramTag = (ParamTag) tag;
        buffer.append("<" + paramTag.parameterName() + ">");
        String text = paramTag.parameterComment();
        if (text.length() > 0) {
            buffer.append(' ').append(render(text, true));
        }
        return;
    }
    buffer.append(render(tag.text(), true));
}

public String getTagText(Tag tag)
{
    if (tag.name().equals("@see"))
    {
        try
        {
            return docWriter.seeTagToString((SeeTag) tag);
        } catch (ClassCastException e)
        {
            System.err.println("Error bulding @see tag " + tag.name());
            return tag.text();
        }
    } else if (tag.name().equals("@param"))
    {
        return buildParamTagText((ParamTag) tag);
    } else if (tag.name().equals("@throws") || tag.name().equals("@exception"))
    {
        return buildThrowTag((ThrowsTag) tag);
    }

    return tag.text();
}

/**
 * Returns the XML for a parameter and its corresponding param tag.
 *
 * @return The corresponding XML.
 */
private static XMLNode toParameterNode(Parameter parameter, ParamTag tag, boolean isVarArgs) {
  if (parameter == null) return null;
  XMLNode node = new XMLNode("parameter");
  node.attribute("name", parameter.name());
  node.attribute("type", parameter.type().typeName());
  node.attribute("fulltype", parameter.type().toString());

  String dimension = parameter.type().dimension();

  if (isVarArgs) {
    dimension = dimension.replaceAll("\\[\\]$", "") + "...";
  }

  node.attribute("dimension", dimension);
  node.attribute("varargs", isVarArgs);

  if (tag!= null) {
    node.text(toComment(tag));
  }

  return node;
}

protected String getParamComment(MethodDoc method, String paramName) {
    ParamTag[] paramTags = method.paramTags();
    for (ParamTag paramTag : paramTags) {
        if (paramTag.parameterName().equals(paramName)) {
            return paramTag.parameterComment();
        }
    }
    return null;
}

/**
 * Returns the XML for the specified parameters using the param tags for additional description.
 *
 * @param parameters parameters instances to process
 * @param tags       corresponding parameter tags (not necessarily in the same order)
 *
 * @return the XML for the specified parameters using the param tags for additional description.
 */
private static XMLNode toParametersNode(Parameter[] parameters, ParamTag[] tags) {
  if (parameters.length == 0) return null;

  // Iterate over the parameters
  XMLNode node = new XMLNode("parameters");
  for (Parameter parameter : parameters) {
    XMLNode p = toParameterNode(parameter, find(tags, parameter.name()));
    node.child(p);
  }

  return node;
}

/**
 * Returns the XML for a parameter and its corresponding param tag.
 *
 * @return The corresponding XML.
 */
private static XMLNode toParameterNode(Parameter parameter, ParamTag tag) {
  if (parameter == null) return null;
  XMLNode node = new XMLNode("parameter");
  node.attribute("name", parameter.name());
  node.attribute("type", parameter.type().typeName());
  node.attribute("fulltype", parameter.type().toString());
  if (tag!= null) {
    node.text(toComment(tag));
  }
  return node;
}

/**
 * Find the corresponding parameter tag.
 *
 * @return
 */
private static ParamTag find(ParamTag[] tags, String name){
  for (ParamTag tag : tags) {
    if (tag.parameterName().equalsIgnoreCase(name)) return tag;
  }
  return null;
}

public static MethodDocumentation fromMethodDoc(MethodDoc methodDoc) {
    MethodDocumentation md = new MethodDocumentation();
    md.comment = methodDoc.commentText();

    for (Tag tag : methodDoc.tags()) {
        if (tag instanceof ParamTag) {
            ParamTag paramTag = (ParamTag) tag;
            md.parameters.put(paramTag.parameterName(), paramTag.parameterComment());
        } else {
            md.tags.put(cleanupTagName(tag.name()), tag.text());
        }
    }

    return md;
}

private static ParamTag getParamTag(ParamTag[] paramTags, String name) {
    for (ParamTag paramTag : paramTags) {
    if (paramTag.parameterName().equals(name)) {
        return paramTag;
    }
}

    return null;
  }

/**
 * @return the @param tag comment for the given methodDoc and parameter, or null if not found.
 */
protected String getParamTagComment(MethodDoc methodDoc, String parameterName) {

    if (methodDoc == null) {
        return null;
    }

    for (ParamTag paramTag : Cawls.safeIterable(methodDoc.paramTags())) {
        if (paramTag.parameterName().equals( parameterName )) {
            return paramTag.parameterComment();
        }
    }

    return null;
}

/**
 * @return the @param tag for the given parameterName
 */
protected ParamTag getParamTag(ParamTag[] paramTags, String parameterName) {

    for (ParamTag paramTag : Cawls.safeIterable(paramTags)) {
        if (paramTag.parameterName().equals( parameterName )) {
            return paramTag;
        }
    }

    return null;
}

/**
 * Resolve inherited @param tags.
 *
 * This method compiles a list of param tags for each of the given methodDoc's parameters.
 * If a paramTag is missing from the given methodDoc, it is searched for in the method's
 * inheritance chain.
 * 
 * @return a list of @param tags for the given methodDoc, some of which may be inherited.
 */
protected List<ParamTag> getInheritedParamTags(MethodDoc methodDoc, MethodDoc specifiedByMethodDoc) {

    List<ParamTag> retMe = new ArrayList<ParamTag>();

    for ( Parameter parameter : methodDoc.parameters() ) {

        ParamTag paramTag = getInheritedParamTag( methodDoc, parameter.name(), specifiedByMethodDoc);
        if (paramTag != null) {
            retMe.add( paramTag );
        } 
    }

    return retMe;
}

/**
 * @return full JSON objects for the given ParamTag[]
 */
protected JSONArray processParamTags(ParamTag[] paramTags) {
    JSONArray retMe = new JSONArray();

    for (ParamTag paramTag : paramTags) {
        retMe.add(processParamTag(paramTag));
    }

    return retMe;
}

/**
 * @return the full JSON for the given ParamTag
 */
protected JSONObject processParamTag(ParamTag paramTag) {
    if (paramTag == null) {
        return null;
    }

    JSONObject paramJson = processTag(paramTag);
    paramJson.put("parameterComment", paramTag.parameterComment());
    paramJson.put("parameterName", paramTag.parameterName());

    return paramJson;
}

public static boolean start(RootDoc root) throws IOException {
    parseOptions(root.options());
    ResourceInfo resourceInfo = new ResourceInfo();
    for (ClassDoc clazz : root.classes()) {
        Resource resource = null;
        for (MethodDoc method : clazz.methods()) {
            if (getAnnotation(method, "org.apache.axis2.transport.testkit.tests.Setup") != null) {
                if (resource == null) {
                    resource = new Resource(clazz.qualifiedName());
                }
                ParamTag[] paramTags = method.paramTags();
                for (Parameter parameter : method.parameters()) {
                    Type type = parameter.type();
                    String name = parameter.name();
                    String comment = null;
                    for (ParamTag paramTag : paramTags) {
                        if (paramTag.parameterName().equals(name)) {
                            comment = paramTag.parameterComment();
                            break;
                        }
                    }
                    if (comment == null) {
                        comment = getFirstSentence(root.classNamed(type.qualifiedTypeName()));
                    }
                    resource.addDependency(type.qualifiedTypeName(),
                                           type.dimension().equals("[]") ? "0..*" : "1", 
                                           comment);
                }
            }
        }
        if (resource != null) {
            resourceInfo.addResource(resource);
        }
    }
    ObjectOutputStream out = new ObjectOutputStream(new FileOutputStream(outFile));
    out.writeObject(resourceInfo);
    out.close();
    return true;
}

/**
 * Returns the XML for the specified parameters using the param tags for additional description.
 *
 * @param parameters parameters instances to process
 * @param tags       corresponding parameter tags (not necessarily in the same order)
 *
 * @return the XML for the specified parameters using the param tags for additional description.
 */
private static XMLNode toParametersNode(Parameter[] parameters, ParamTag[] tags, boolean isVarArgs) {
  if (parameters.length == 0) return null;

  // Iterate over the parameters
  XMLNode node = new XMLNode("parameters");
  int pos = 0;
  for (Parameter parameter : parameters) {
    XMLNode p = toParameterNode(parameter, find(tags, parameter.name()), isVarArgs && pos++ == (parameters.length - 1));
    node.child(p);
  }

  return node;
}

/**
 * Find the corresponding parameter tag.
 *
 * @return
 */
private static ParamTag find(ParamTag[] tags, String name){
  for (ParamTag tag : tags) {
    if (tag.parameterName().equalsIgnoreCase(name)) {
      return tag;
    }
  }
  return null;
}

private String getParamComment(ParamTag[] paramTags, String paramName)
{
  for (ParamTag tag : paramTags)
  {
    if (tag.parameterName().equals(paramName))
    {
      return tag.parameterComment();
    }
  }

  return null;
}

private static String renderParameterName(ParamTag tag) {
    if (!tag.isTypeParameter()) {
        return tag.parameterName();
    }
    else {
        return '<' + tag.parameterName() + '>';
    }
}

/**
 * Either the paramTag exists or it doesn't.  If it doesn't, inherit.
 * If it does, and contains {@inheritDoc}, resolve inherited doc.
 *
 * @return retMe
 */
protected JSONObject inheritParamTags(JSONObject retMe, MethodDoc methodDoc, MethodDoc specifiedByMethodDoc) {

    // First things first - compile a list of ParamTags.  If any are missing,
    // inherit from the parent class.
    List<ParamTag> paramTags = getInheritedParamTags(methodDoc, specifiedByMethodDoc);

    List<Map> paramTagModels = new ArrayList<Map>();

    for ( ParamTag paramTag : paramTags ) {

        Map paramTagModel = processParamTag(paramTag);

        paramTagModel.put("parameterComment",  getInheritedParamTagComment(methodDoc, paramTag.parameterName(), specifiedByMethodDoc) );

        paramTagModels.add(paramTagModel);
    }

    retMe.put("paramTags", paramTagModels);

    return retMe;
}

private String buildParamTagText(ParamTag tag)
{
    String result = "<font class='tagInfo'>" + tag.parameterName() + "</font>";
    result += " - " + tag.parameterComment();
    return result;
}

/**
 * Generates a child node for each generic type parameter.
 * @param  doc [description]
 * @return     [description]
 */
private static XMLNode toTypeParametersNode(ClassDoc doc) {
  TypeVariable[] typeParameters = doc.typeParameters();
  ParamTag[] typeParameterTags = doc.typeParamTags();

  XMLNode node = null;

  if (typeParameters != null && typeParameters.length > 0) {
    node = new XMLNode("typeParameters");

    for (TypeVariable i : typeParameters) {
      XMLNode paramNode = new XMLNode("parameter");
      paramNode.attribute("name", i.typeName());

      Type[] bounds = i.bounds();

      if (bounds != null && bounds.length > 0) {
        XMLNode boundsNode = new XMLNode("bounds");

        for (Type t : bounds) {
          XMLNode typeNode = new XMLNode("type");

          typeNode.attribute("fulltype", t.toString());
          typeNode.attribute("type", t.typeName());
          typeNode.attribute("name", t.qualifiedTypeName());

          boundsNode.child(typeNode);
        }

        paramNode.child(boundsNode);
      }

      if (typeParameterTags != null && typeParameterTags.length > 0) {
        ParamTag tag = null;

        for (ParamTag j : typeParameterTags) {
          // take the first one
          if (j.isTypeParameter() && j.parameterName().equals(i.typeName())) {
            tag = j;
            break;
          }
        }

        if (tag != null) {
          XMLNode commentNode = new XMLNode("comment");
          commentNode.text(toComment(tag));
          paramNode.child(commentNode);
        }
      }

      node.child(paramNode);
    }
  }

  return node;
}

@Override
public void render(ParamTag tag, StringBuilder target, MarkdownDoclet doclet) {
    target.append(tag.name())
            .append(' ').append(renderParameterName(tag))
            .append(' ').append(TagRendering.simplifySingleParagraph(doclet.toHtml(tag.parameterComment())));
}