com.sun.source.doctree.DocTree.Kind Java Examples

public Content getDocLink(LinkInfoImpl.Kind context, TypeElement typeElement, Element element,
        Content label, boolean strong, boolean isProperty) {
    if (! (utils.isIncluded(element) || utils.isLinkable(typeElement))) {
        return label;
    } else if (utils.isExecutableElement(element)) {
        ExecutableElement ee = (ExecutableElement)element;
        return getLink(new LinkInfoImpl(configuration, context, typeElement)
            .label(label)
            .where(getName(getAnchor(ee, isProperty)))
            .strong(strong));
    } else if (utils.isVariableElement(element) || utils.isTypeElement(element)) {
        return getLink(new LinkInfoImpl(configuration, context, typeElement)
            .label(label)
            .where(getName(element.getSimpleName().toString()))
            .strong(strong));
    } else {
        return label;
    }
}
 

/**
 * Return the link for the given member.
 *
 * @param context the id of the context where the link will be added
 * @param typeElement the typeElement that we should link to.  This is not
             necessarily equal to element.containingClass().  We may be
             inheriting comments
 * @param element the member being linked to
 * @param label the label for the link
 * @return the link for the given member
 */
public Content getDocLink(LinkInfoImpl.Kind context, TypeElement typeElement, Element element,
        Content label) {
    if (! (utils.isIncluded(element) || utils.isLinkable(typeElement))) {
        return label;
    } else if (utils.isExecutableElement(element)) {
        ExecutableElement emd = (ExecutableElement) element;
        return getLink(new LinkInfoImpl(configuration, context, typeElement)
            .label(label)
            .where(getName(getAnchor(emd))));
    } else if (utils.isVariableElement(element) || utils.isTypeElement(element)) {
        return getLink(new LinkInfoImpl(configuration, context, typeElement)
            .label(label).where(getName(element.getSimpleName().toString())));
    } else {
        return label;
    }
}
 

/**
 * Build the summary for the fields.
 *
 * @param node the XML element that specifies which components to document
 * @param memberSummaryTree the content tree to which the documentation will be added
 */
public void buildFieldsSummary(XMLNode node, Content memberSummaryTree) {
    MemberSummaryWriter writer =
            memberSummaryWriters.get(VisibleMemberMap.Kind.FIELDS);
    VisibleMemberMap visibleMemberMap =
            getVisibleMemberMap(VisibleMemberMap.Kind.FIELDS);
    addSummary(writer, visibleMemberMap, true, memberSummaryTree);
}
 

@Override @DefinedBy(Api.COMPILER_TREE)
public DCThrows newExceptionTree(ReferenceTree name, List<? extends DocTree> description) {
    // TODO: verify the reference is just to a type (not a field or method)
    DCThrows tree = new DCThrows(Kind.EXCEPTION, (DCReference) name, cast(description));
    tree.pos = pos;
    return tree;
}
 

/**
 * Build the method summary.
 *
 * @param node the XML element that specifies which components to document
 * @param memberSummaryTree the content tree to which the documentation will be added
 */
public void buildMethodsSummary(XMLNode node, Content memberSummaryTree) {
    MemberSummaryWriter writer =
            memberSummaryWriters.get(VisibleMemberMap.Kind.METHODS);
    VisibleMemberMap visibleMemberMap =
           getVisibleMemberMap(VisibleMemberMap.Kind.METHODS);
    addSummary(writer, visibleMemberMap, true, memberSummaryTree);
}
 

private boolean containsParam(List<? extends DocTree> blockTags, String name) {
    for (DocTree blockTag : blockTags) {
        if(blockTag.getKind() == Kind.PARAM) {
            ParamTree param = (ParamTree) blockTag;
            if(name.contentEquals(param.getName().getName())) {
                return true;
            }
        }
    }
    return false;
}
 

/**
 * Build the summary for the nested classes.
 *
 * @param node the XML element that specifies which components to document
 * @param memberSummaryTree the content tree to which the documentation will be added
 */
public void buildNestedClassesSummary(XMLNode node, Content memberSummaryTree) {
    MemberSummaryWriter writer =
            memberSummaryWriters.get(VisibleMemberMap.Kind.INNER_CLASSES);
    VisibleMemberMap visibleMemberMap =
            getVisibleMemberMap(VisibleMemberMap.Kind.INNER_CLASSES);
    addSummary(writer, visibleMemberMap, true, memberSummaryTree);
}
 

@Override @DefinedBy(Api.COMPILER_TREE)
public DCThrows newExceptionTree(ReferenceTree name, List<? extends DocTree> description) {
    // TODO: verify the reference is just to a type (not a field or method)
    DCThrows tree = new DCThrows(Kind.EXCEPTION, (DCReference) name, cast(description));
    tree.pos = pos;
    return tree;
}
 

@Override @DefinedBy(Api.COMPILER_TREE)
public DCThrows newThrowsTree(ReferenceTree name, List<? extends DocTree> description) {
    // TODO: verify the reference is just to a type (not a field or method)
    DCThrows tree = new DCThrows(Kind.THROWS, (DCReference) name, cast(description));
    tree.pos = pos;
    return tree;
}
 

/**
 * Retrieve the class link with the package portion of the label in
 * plain text.  If the qualifier is excluded, it will not be included in the
 * link label.
 *
 * @param typeElement the class to link to.
 * @param isStrong true if the link should be strong.
 * @return the link with the package portion of the label in plain text.
 */
public Content getPreQualifiedClassLink(LinkInfoImpl.Kind context,
        TypeElement typeElement, boolean isStrong) {
    ContentBuilder classlink = new ContentBuilder();
    PackageElement pkg = utils.containingPackage(typeElement);
    if (pkg != null && ! configuration.shouldExcludeQualifier(pkg.getSimpleName().toString())) {
        classlink.addContent(getEnclosingPackageName(typeElement));
    }
    classlink.addContent(getLink(new LinkInfoImpl(configuration,
            context, typeElement).label(utils.getSimpleName(typeElement)).strong(isStrong)));
    return classlink;
}
 

/**
 * Returns true if the element is included, contains @hidden tag,
 * or if javafx flag is present and element contains @treatAsPrivate
 * tag.
 * @param e the queried element
 * @return true if it exists, false otherwise
 */
public boolean isHidden(Element e) {
    // prevent needless tests on elements which are not included
    if (!isIncluded(e)) {
        return false;
    }
    if (configuration.javafx &&
            hasBlockTag(e, DocTree.Kind.UNKNOWN_BLOCK_TAG, "treatAsPrivate")) {
        return true;
    }
    return hasBlockTag(e, DocTree.Kind.HIDDEN);
}
 

private boolean shouldDocument(Element e) {
    if (shouldDocumentVisitor == null) {
        shouldDocumentVisitor = new SimpleElementVisitor9<Boolean, Void>() {
            private boolean hasSource(TypeElement e) {
                return configuration.docEnv.getFileKind(e) ==
                        javax.tools.JavaFileObject.Kind.SOURCE;
            }

            // handle types
            @Override
            public Boolean visitType(TypeElement e, Void p) {
                return configuration.docEnv.isSelected(e) && hasSource(e);
            }

            // handle everything else
            @Override
            protected Boolean defaultAction(Element e, Void p) {
                return configuration.docEnv.isSelected(e);
            }

            @Override
            public Boolean visitUnknown(Element e, Void p) {
                throw new AssertionError("unkown element: " + p);
            }
        };
    }
    return shouldDocumentVisitor.visit(e);
}
 

private List<? extends DocTree> getBlockTags0(Element element, DocTree.Kind... kinds) {
    DocCommentTree dcTree = getDocCommentTree(element);
    if (dcTree == null)
        return Collections.emptyList();

    return filteredList(dcTree.getBlockTags(), kinds);
}
 

public void addClassesSummary(SortedSet<TypeElement> classes, String label,
        String tableSummary, List<String> tableHeader, Content summaryContentTree) {
    if (!classes.isEmpty()) {
        Content caption = getTableCaption(new RawHtml(label));
        Content table = (configuration.isOutputHtml5())
                ? HtmlTree.TABLE(HtmlStyle.typeSummary, caption)
                : HtmlTree.TABLE(HtmlStyle.typeSummary, tableSummary, caption);
        table.addContent(getSummaryTableHeader(tableHeader, "col"));
        Content tbody = new HtmlTree(HtmlTag.TBODY);
        boolean altColor = true;
        for (TypeElement te : classes) {
            if (!utils.isCoreClass(te) ||
                !configuration.isGeneratedDoc(te)) {
                continue;
            }
            Content classContent = getLink(new LinkInfoImpl(
                    configuration, LinkInfoImpl.Kind.PACKAGE, te));
            Content tdClass = HtmlTree.TH_ROW_SCOPE(HtmlStyle.colFirst, classContent);
            HtmlTree tr = HtmlTree.TR(tdClass);
            tr.addStyle(altColor ? HtmlStyle.altColor : HtmlStyle.rowColor);
            altColor = !altColor;
            HtmlTree tdClassDescription = new HtmlTree(HtmlTag.TD);
            tdClassDescription.addStyle(HtmlStyle.colLast);
            if (utils.isDeprecated(te)) {
                tdClassDescription.addContent(getDeprecatedPhrase(te));
                List<? extends DocTree> tags = utils.getDeprecatedTrees(te);
                if (!tags.isEmpty()) {
                    addSummaryDeprecatedComment(te, tags.get(0), tdClassDescription);
                }
            } else {
                addSummaryComment(te, tdClassDescription);
            }
            tr.addContent(tdClassDescription);
            tbody.addContent(tr);
        }
        table.addContent(tbody);
        summaryContentTree.addContent(table);
    }
}
 

/**
 * Build the summary for the optional members.
 *
 * @param node the XML element that specifies which components to document
 * @param memberSummaryTree the content tree to which the documentation will be added
 */
public void buildAnnotationTypeRequiredMemberSummary(XMLNode node, Content memberSummaryTree) {
    MemberSummaryWriter writer =
            memberSummaryWriters.get(VisibleMemberMap.Kind.ANNOTATION_TYPE_MEMBER_REQUIRED);
    VisibleMemberMap visibleMemberMap =
            getVisibleMemberMap(VisibleMemberMap.Kind.ANNOTATION_TYPE_MEMBER_REQUIRED);
    addSummary(writer, visibleMemberMap, false, memberSummaryTree);
}
 

/**
 * Build the summary for the optional members.
 *
 * @param node the XML element that specifies which components to document
 * @param memberSummaryTree the content tree to which the documentation will be added
 */
public void buildAnnotationTypeOptionalMemberSummary(XMLNode node, Content memberSummaryTree) {
    MemberSummaryWriter writer =
            memberSummaryWriters.get(VisibleMemberMap.Kind.ANNOTATION_TYPE_MEMBER_OPTIONAL);
    VisibleMemberMap visibleMemberMap =
            getVisibleMemberMap(VisibleMemberMap.Kind.ANNOTATION_TYPE_MEMBER_OPTIONAL);
    addSummary(writer, visibleMemberMap, false, memberSummaryTree);
}
 

/**
 * Build the summary for the fields.
 */
public void buildPropertiesSummary(XMLNode node, Content memberSummaryTree) {
    MemberSummaryWriter writer =
            memberSummaryWriters.get(VisibleMemberMap.Kind.PROPERTIES);
    VisibleMemberMap visibleMemberMap =
            getVisibleMemberMap(VisibleMemberMap.Kind.PROPERTIES);
    addSummary(writer, visibleMemberMap, true, memberSummaryTree);
}
 

/**
 * Return true it there are any members to summarize.
 *
 * @return true if there are any members to summarize.
 */
@Override
public boolean hasMembersToDocument() {
    if (utils.isAnnotationType(typeElement)) {
        return !utils.getAnnotationMethods(typeElement).isEmpty();
    }
    for (VisibleMemberMap.Kind kind : VisibleMemberMap.Kind.values()) {
        VisibleMemberMap members = getVisibleMemberMap(kind);
        if (!members.noVisibleMembers()) {
            return true;
        }
    }
    return false;
}
 

/**
 * Construct a new MemberSummaryBuilder.
 *
 * @param annotationTypeWriter the writer for the class whose members are
 *                             being summarized.
 * @param configuration the current configuration of the doclet.
 */
public static MemberSummaryBuilder getInstance(
        AnnotationTypeWriter annotationTypeWriter, Context context) {
    MemberSummaryBuilder builder = new MemberSummaryBuilder(context,
            annotationTypeWriter.getAnnotationTypeElement());
    WriterFactory wf = context.configuration.getWriterFactory();
    for (VisibleMemberMap.Kind kind : VisibleMemberMap.Kind.values()) {
        MemberSummaryWriter msw = builder.getVisibleMemberMap(kind).noVisibleMembers()
                ? null
                : wf.getMemberSummaryWriter(annotationTypeWriter, kind);
        builder.memberSummaryWriters.put(kind, msw);
    }
    return builder;
}
 

/**
 * Construct a new MemberSummaryBuilder.
 *
 * @param classWriter   the writer for the class whose members are being
 *                      summarized.
 * @param context       the build context.
 */
public static MemberSummaryBuilder getInstance(
        ClassWriter classWriter, Context context) {
    MemberSummaryBuilder builder = new MemberSummaryBuilder(context,
            classWriter.getTypeElement());
    WriterFactory wf = context.configuration.getWriterFactory();
    for (VisibleMemberMap.Kind kind : VisibleMemberMap.Kind.values()) {
        MemberSummaryWriter msw =  builder.getVisibleMemberMap(kind).noVisibleMembers()
                ? null
                : wf.getMemberSummaryWriter(classWriter, kind);
        builder.memberSummaryWriters.put(kind, msw);
    }
    return builder;
}
 

public boolean hasBlockTag(Element element, DocTree.Kind kind, final String tagName) {
    CommentHelper ch = getCommentHelper(element);
    String tname = tagName != null && tagName.startsWith("@")
            ? tagName.substring(1)
            : tagName;
    for (DocTree dt : getBlockTags(element, kind)) {
        if (dt.getKind() == kind) {
            if (tname == null || ch.getTagName(dt).equals(tname)) {
                return true;
            }
        }
    }
    return false;
}
 

public List<? extends DocTree> getBlockTags(Element element, String tagName) {
    DocTree.Kind kind = null;
    switch (tagName) {
        case "author":
        case "deprecated":
        case "hidden":
        case "param":
        case "return":
        case "see":
        case "serial":
        case "since":
        case "throws":
        case "exception":
        case "version":
            kind = DocTree.Kind.valueOf(tagName.toUpperCase());
            return getBlockTags(element, kind);
        case "serialData":
            kind = SERIAL_DATA;
            return getBlockTags(element, kind);
        case "serialField":
            kind = SERIAL_FIELD;
            return getBlockTags(element, kind);
        default:
            kind = DocTree.Kind.UNKNOWN_BLOCK_TAG;
            break;
    }
    List<? extends DocTree> blockTags = getBlockTags(element, kind);
    List<DocTree> out = new ArrayList<>();
    String tname = tagName.startsWith("@") ? tagName.substring(1) : tagName;
    CommentHelper ch = getCommentHelper(element);
    for (DocTree dt : blockTags) {
        if (ch.getTagName(dt).equals(tname)) {
            out.add(dt);
        }
    }
    return out;
}
 

public List<? extends DocTree> filteredList(List<? extends DocTree> dlist, DocTree.Kind... select) {
    List<DocTree> list = new ArrayList<>(dlist.size());
    if (select == null)
        return dlist;
    for (DocTree dt : dlist) {
        if (dt.getKind() != ERRONEOUS) {
            for (DocTree.Kind kind : select) {
                if (dt.getKind() == kind) {
                    list.add(dt);
                }
            }
        }
    }
    return list;
}
 

public DCLiteral Literal(DCText text) {
    DCLiteral tree = new DCLiteral(Kind.LITERAL, text);
    tree.pos = pos;
    return tree;
}
 

private boolean isKind(DocTree doctree, DocTree.Kind match) {
    return  doctree.getKind() == match;
}
 

public DCThrows Throws(DCReference name, List<DCTree> description) {
    DCThrows tree = new DCThrows(Kind.THROWS, name, description);
    tree.pos = pos;
    return tree;
}
 

public List<? extends DocTree> getBlockTags(Element element, DocTree.Kind... kinds) {
    return getBlockTags0(element, kinds);
}
 

public boolean hasBlockTag(Element element, DocTree.Kind kind) {
    return hasBlockTag(element, kind, null);
}
 

public DCThrows Throws(DCReference name, List<DCTree> description) {
    DCThrows tree = new DCThrows(Kind.THROWS, name, description);
    tree.pos = pos;
    return tree;
}
 

public DCThrows Exception(DCReference name, List<DCTree> description) {
    DCThrows tree = new DCThrows(Kind.EXCEPTION, name, description);
    tree.pos = pos;
    return tree;
}