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

private static boolean exclude(Doc doc) {
    // if (doc.name().contains("UnitTest")) {
    // return true;
    // }
    if (doc != null) {
        if (doc.tags(EXCLUDE_TAG).length > 0) {
            return true;
        } else if (doc instanceof ProgramElementDoc) {
            if (exclude(((ProgramElementDoc) doc).containingPackage())) {
                return true;
            } else if (exclude(((ProgramElementDoc) doc).containingClass())) {
                return true;
            }
        }
    }
    // nothing above found a reason to exclude
    return false;
}

/**
 * Appends to the current document a link that is
 * built from the given ``element``. Such links is
 * usually leading to the internal corresponding
 * document section
 * 
 * @param element Element to build link from.
 */
public void linkedName(final ProgramElementDoc element) {
    final StringBuffer anchorBuilder = new StringBuffer()
        .append('#')
        .append(element.name());
    if (element instanceof ExecutableMemberDoc) {
        final ExecutableMemberDoc member = (ExecutableMemberDoc) element;
        final Parameter[] parameters = member.parameters();
        if (parameters.length == 0) { // Empty constructor case.

        }
        for (int i = 0; i < parameters.length; i++) {
            anchorBuilder.append(parameters[i].type().simpleTypeName());
            if (i < parameters.length - 1) {
                anchorBuilder.append('-');
            }
        }
    }
    final String url = anchorBuilder.toString().toLowerCase();
    link(element.name(), url);
}

public static boolean start(final RootDoc root) {
    for (final ClassDoc cls : root.classes()) {
        final List<ProgramElementDoc> elements = new LinkedList<>();
        elements.add(cls);
        elements.addAll(Arrays.asList(cls.constructors()));
        elements.addAll(Arrays.asList(cls.methods()));
        for (final ProgramElementDoc elem : elements) {
            for (final Tag tag : elem.inlineTags()) {
                final String name = tag.name();
                if (name.equals("@code") && tag.text().trim().startsWith(">")) {
                    generateRunner(cls, elem, tag);
                }
            }
        }
    }
    return true;
}

public String formatModifiers(ProgramElementDoc doc) {
    StringBuffer sb = new StringBuffer(32);
    if (doc.isPublic()) {
        sb.append("public ");
    }
    if (doc.isPrivate()) {
        sb.append("private ");
    }
    if (doc.isProtected()) {
        sb.append("protected ");
    }
    if (doc.isStatic()) {
        sb.append("static ");
    }
    if (doc.isInterface()) {
        sb.append("interface ");
    }
    if (doc.isFinal()) {
        sb.append("final ");
    }
    if (doc.isClass()) {
        sb.append("class ");
    }
    return (sb.length() == 0) ? "" : color(sb.toString(), "blue");
}

public String getLink(ProgramElementDoc doc, int context)
{
    ClassDoc cdoc = doc.containingClass();
    if (doc instanceof ClassDoc || doc.isInterface() || doc.isEnum() || doc.isError() || doc.isException() || doc.isAnnotationType())
    {
        cdoc = (ClassDoc) doc;
    }

    LinkInfoImpl lnInfo = new LinkInfoImpl(context, cdoc, "", null);
    if (lnInfo == null)
    {
        return null;
    }
    String link = docWriter.getLink(lnInfo);
    if (link == null)
    {
        return null;
    }
    return getHref(link) + "#" + getSignature(doc);
}

protected boolean isProgramElementDocAnnotatedWith(ProgramElementDoc elementDoc, String annotation) {
    AnnotationDesc[] annotations = elementDoc.annotations();
    for (int i = 0; i < annotations.length; i++) {
        if (annotations[i].annotationType().qualifiedTypeName().equals(annotation)) {
            return true;
        }
    }
    return false;
}

private static String commentText(ProgramElementDoc doc) {
    if (doc instanceof MethodDoc) {
        MethodDoc method = (MethodDoc) doc;

        return Javadocs.commentText(method).orElse("");
    } else return doc.commentText();
}

/**
 * Reconstitute the class name from the given class JavaDoc object.
 *
 * @param doc the Javadoc model for the given class.
 * @return The (string) class name of the given class.
 */
protected static String getClassName(ProgramElementDoc doc, boolean binaryName) {
    PackageDoc containingPackage = doc.containingPackage();
    String className = doc.name();
    if (binaryName) {
        className = className.replaceAll("\\.", "\\$");
    }
    return containingPackage.name().length() > 0 ?
            String.format("%s.%s", containingPackage.name(), className) :
            String.format("%s", className);
}

static IndentingPrintWriter writeAccessibility(IndentingPrintWriter out, ProgramElementDoc element) {
    if (element.isStatic()) {
        out.append("{static}").whitespace();
    }
    return element.isPrivate() ? out.append('-')
            : element.isProtected() ? out.append('#')
            : element.isPackagePrivate() ? out.append('~')
            : out.append('+');
}

static Optional<AnnotationDesc> annotationNamed(
    ProgramElementDoc doc, String annotationName) {
  for (AnnotationDesc a : doc.annotations()) {
    if (annotationName.equals(a.annotationType().qualifiedTypeName())) {
      return Optional.of(a);
    }
  }
  return Optional.absent();
}

/**
 * Sets the visibility for the class, method or field.
 *
 * @param member The member for which the visibility needs to be set (class, method, or field).
 * @param node The node to which the visibility should be set.
 */
private static String getVisibility(ProgramElementDoc member) {
  if (member.isPrivate()) return "private";
  if (member.isProtected()) return "protected";
  if (member.isPublic()) return "public";
  if (member.isPackagePrivate()) return "package-private";
  // Should never happen
  return null;
}

/**
 * Returns string representation of scope
 * 
 * @param doc
 * @return
 */
protected String parseScope(ProgramElementDoc doc) {
  if (doc.isPrivate()) {
    return "private";
  } else if (doc.isProtected()) {
    return "protected";
  } else if (doc.isPublic()) {
    return "public";
  }
  return "";
}

public static AnnotationDesc getAnnotationDesc(ProgramElementDoc doc, Class<? extends Annotation> annotationClz) {
    for (AnnotationDesc annotationDesc : doc.annotations()) {
        if (annotationDesc.annotationType()
                .qualifiedTypeName().equals(annotationClz.getName())) {
            return annotationDesc;
            }
    }
    return null;
}

/**
 * Appends to the current document the ``member``
 * returns label, which is composed of the given
 * ``member`` modifiers if any, followed by the
 * return type link, if the given ``member`` is
 * a method, 
 * 
 * @param element Member to build return label for.
 */
public void returnSignature(final ProgramElementDoc element) {
    code(element.modifiers());
    if (element.isMethod()) {
        final MethodDoc method = (MethodDoc) element;
        character(' ');
        // TODO : Consider using source instance instead.
        typeLink(method.containingPackage(), method.returnType());
    }
}

/**
 * Appends to the current document the signature
 * of the given ``member`` as a table row.
 * 
 * @param element Member to write signature from.
 */
public void rowSignature(final ProgramElementDoc element) {
    startTableRow();
    returnSignature(element);
    cell();
    linkedName(element);
    if (element instanceof ExecutableMemberDoc) {
        final ExecutableMemberDoc member = (ExecutableMemberDoc) element;
        inlineParameters(member.parameters());
    }
    endTableRow();
    newLine();
}

/**
 * Appends to the current document the signature
 * of the given ``member`` as a list item.
 * 
 * @param element Member to write signature from.
 */
public void itemSignature(final ProgramElementDoc element) {
    item();
    returnSignature(element);
    character(' ');
    linkedName(element);
    if (element instanceof ExecutableMemberDoc) {
        final ExecutableMemberDoc member = (ExecutableMemberDoc) element;
        inlineParameters(member.parameters());
    }
    newLine();
}

/** Forwards to {@link #analyze(ProgramElementDoc, IJavaElement)}. */
@Override
public void analyze(ClassDoc docElement, IJavaElement element)
        throws ConQATException {
    analyze((ProgramElementDoc) docElement, element);

}

/** Check comment. */
private void analyzeSimply(ProgramElementDoc docElement,
        IJavaElement element) throws ConQATException {
    if (isInsufficient(docElement.commentText())) {
        createFinding(docElement, element);
    }
}

/** Create finding for insufficient comments. */
private void createFinding(ProgramElementDoc docElement,
        IJavaElement element) throws ConQATException {
    createFinding(
            docElement.qualifiedName() + " has insufficient comment.",
            docElement, element);
}

/** Checks if an element has an inline tag with the specified name. */
private boolean hasInlineTag(ProgramElementDoc docElement, String tagName) {
    for (Tag tag : docElement.inlineTags()) {
        if (tag.name().equals(tagName)) {
            return true;
        }
    }
    return false;
}

/** {@inheritDoc} */
@Override
public void analyze(ProgramElementDoc docElement, IJavaElement element) throws ConQATException{
    if (docElement.getRawCommentText().toLowerCase()
            .contains(tagName.toLowerCase())
            && !hasInlineTag(docElement, tagName)) {
        createFinding(docElement.qualifiedName() + " has invalid "
                + tagName + " tag.", docElement, element);
    }
}

/** {@inheritDoc} */
@Override
public void analyze(ProgramElementDoc docElement, IJavaElement element)
        throws ConQATException {
    if (docElement.tags(tagName).length == 0) {
        createFinding(docElement.qualifiedName() + " has no " + tagName
                + " tag.", docElement, element);
    }
}

/** {@inheritDoc} */
@Override
public void analyze(ProgramElementDoc docElement, IJavaElement element)
        throws ConQATException {
    if (StringUtils.isEmpty(docElement.getRawCommentText())) {
        createFinding(
                docElement.qualifiedName() + " has no documentation.",
                docElement, element);
    }
}

/** This creates a finding in the analyzer's finding group. */
protected Finding createFinding(String message, ProgramElementDoc doc,
        IJavaElement element) throws ConQATException {
    int startLine = doc.position().line();
    // use max to protect against empty string
    int lineCount = Math.max(1,
            StringUtils.countLines(doc.getRawCommentText()));
    return ResourceUtils.createAndAttachFindingForFilteredLineRegion(
            findingGroup, message, element, startLine, startLine
                    + lineCount - 1, JavaDocAnalyzer.KEY);
}

/**
 * @return a JSON stub for the given ProgramElementDoc
 */
protected JSONObject processProgramElementDocStub(ProgramElementDoc peDoc) {
    if (peDoc == null) {
        return null;
    }

    JSONObject retMe = processDocStub(peDoc);

    retMe.put("qualifiedName", peDoc.qualifiedName());
    retMe.put("modifiers", peDoc.modifiers());

    return retMe;
}

private static AnnotationDesc getAnnotation(ProgramElementDoc doc, String qualifiedName) {
    for (AnnotationDesc annotation : doc.annotations()) {
        if (annotation.annotationType().qualifiedName().equals(qualifiedName)) {
            return annotation;
        }
    }
    return null;
}

public String getLink(Doc doc)
{
    if (doc instanceof ProgramElementDoc)
    {
        String link = getLink((ProgramElementDoc) doc, LinkInfoImpl.CONTEXT_INDEX);
        link=link.replaceAll("\\.\\./", "");
        return "<a href='../" + link + "'>" + JOTHTMLUtilities.textToHtml(getSignature(doc),JOTHTMLUtilities.ENCODE_HTML_CHARS) + "</a>";
    }
    return "#######" + doc.name();
}

public AnnotationDesc[] getAnnotations()
{
    Object doc = getVariables().get("curitem");
    if (!(doc instanceof ProgramElementDoc))
    {
        return null;
    }
    return getAnnotations((ProgramElementDoc) doc);
}

/**
 * Sets the visibility for the class, method or field.
 *
 * @param member The member for which the visibility needs to be set (class, method, or field).
 * @param node The node to which the visibility should be set.
 */
private static String getVisibility(ProgramElementDoc member) {
  if (member.isPrivate()) return "private";
  if (member.isProtected()) return "protected";
  if (member.isPublic()) return "public";
  if (member.isPackagePrivate()) return "package-private";
  // Should never happen
  return null;
}

private static boolean isAnnotatedWith(ProgramElementDoc elementDoc, String... tagString) {
    AnnotationDesc[] annotations = elementDoc.annotations();

    for (AnnotationDesc annotation : annotations) {

        if (Arrays.asList(tagString).contains(annotation.annotationType().toString())) {
            return true;
        }
    }

    return false;
}

/**
 * {@inheritDoc}
 */
public Comparator<ProgramElementDoc> getMemberComparator() {
    return null;
}

static void printMembers(RootDoc root, ProgramElementDoc[] pgmDocs) {
    for (ProgramElementDoc pgmDoc : pgmDocs) {
        root.printNotice("     " + pgmDoc + ", Comments: " + pgmDoc.getRawCommentText());
    }
}

/**
 * {@inheritDoc}
 */
public Comparator<ProgramElementDoc> getMemberComparator() {
    return null;
}

protected static Class<?> getClassForDoc(ProgramElementDoc doc) throws ClassNotFoundException {
    return Class.forName(getClassName(doc, true));
}

private static Optional<AnnotationDesc> conceptAnnotation(final ProgramElementDoc doc) {
    return Arrays.stream(doc.annotations())
            .filter(d -> isAnnotatedAsConcept(d.annotationType()))
            .findFirst();
}

public static Object getAnnotationValue(ProgramElementDoc doc, Class<? extends Annotation> annotationClz, String name) {
    AnnotationDesc annotationDesc = getAnnotationDesc(doc, annotationClz);
    return annotationDesc == null ? null : getAnnotationDescValue(annotationDesc, name);
}

/** Forwards to {@link #analyze(ProgramElementDoc, IJavaElement)}. */
@Override
public void analyze(MethodDoc docElement, IJavaElement element)
        throws ConQATException {
    analyze((ProgramElementDoc) docElement, element);
}

/** Forwards to {@link #analyze(ProgramElementDoc, IJavaElement)}. */
@Override
public void analyze(FieldDoc docElement, IJavaElement element)
        throws ConQATException {
    analyze((ProgramElementDoc) docElement, element);
}

/** Template method for analyzing a comment. */
public abstract void analyze(ProgramElementDoc docElement,
        IJavaElement element) throws ConQATException;

/**
 * @return the full JSON for the given ProgramElementDoc
 */
protected JSONObject processProgramElementDoc(ProgramElementDoc programElementDoc) {

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

    JSONObject retMe = processDoc(programElementDoc);

    retMe.put("containingPackage", processPackageDocStub(programElementDoc.containingPackage()) );

    packageDocs.add(programElementDoc.containingPackage());

    retMe.put("containingClass", processClassDocStub(programElementDoc.containingClass()) );
    retMe.put("qualifiedName", programElementDoc.qualifiedName());

    retMe.put("modifiers", programElementDoc.modifiers());
    retMe.put("modifierSpecifier", programElementDoc.modifierSpecifier());
    retMe.put("annotations", processAnnotationDescs(programElementDoc.annotations()));

    return retMe;
}