Java Code Examples for com.sun.tools.doclets.internal.toolkit.Content#addContent()

/**
 * Given an array of <code>ParamTag</code>s,return its string representation.
 * Try to inherit the param tags that are missing.
 *
 * @param holder            the doc 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 isNonTypeParams, Doc holder,
        TagletWriter writer, Object[] formalParameters, ParamTag[] paramTags) {
    Content result = writer.getOutputInstance();
    Set<String> alreadyDocumented = new HashSet<String>();
    if (paramTags.length > 0) {
        result.addContent(
            processParamTags(isNonTypeParams, paramTags,
            getRankMap(formalParameters), writer, alreadyDocumented)
        );
    }
    if (alreadyDocumented.size() != formalParameters.length) {
        //Some parameters are missing corresponding @param tags.
        //Try to inherit them.
        result.addContent(getInheritedTagletOutput (isNonTypeParams, holder,
            writer, formalParameters, alreadyDocumented));
    }
    return result;
}
 

/**
 * Given an array of <code>ParamTag</code>s,return its string representation.
 * Try to inherit the param tags that are missing.
 *
 * @param holder            the doc 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 isNonTypeParams, Doc holder,
        TagletWriter writer, Object[] formalParameters, ParamTag[] paramTags) {
    Content result = writer.getOutputInstance();
    Set<String> alreadyDocumented = new HashSet<String>();
    if (paramTags.length > 0) {
        result.addContent(
            processParamTags(isNonTypeParams, paramTags,
            getRankMap(formalParameters), writer, alreadyDocumented)
        );
    }
    if (alreadyDocumented.size() != formalParameters.length) {
        //Some parameters are missing corresponding @param tags.
        //Try to inherit them.
        result.addContent(getInheritedTagletOutput (isNonTypeParams, holder,
            writer, formalParameters, alreadyDocumented));
    }
    return result;
}
 

/**
 * Add links for exceptions that are declared but not documented.
 */
private Content linkToUndocumentedDeclaredExceptions(
        Type[] declaredExceptionTypes, Set<String> alreadyDocumented,
        TagletWriter writer) {
    Content result = writer.getOutputInstance();
    //Add links to the exceptions declared but not documented.
    for (int i = 0; i < declaredExceptionTypes.length; i++) {
        if (declaredExceptionTypes[i].asClassDoc() != null &&
            ! alreadyDocumented.contains(
                    declaredExceptionTypes[i].asClassDoc().name()) &&
            ! alreadyDocumented.contains(
                declaredExceptionTypes[i].asClassDoc().qualifiedName())) {
            if (alreadyDocumented.size() == 0) {
                result.addContent(writer.getThrowsHeader());
            }
            result.addContent(writer.throwsTagOutput(declaredExceptionTypes[i]));
            alreadyDocumented.add(declaredExceptionTypes[i].asClassDoc().name());
        }
    }
    return result;
}
 

/**
 * Add links for exceptions that are declared but not documented.
 */
private Content linkToUndocumentedDeclaredExceptions(
        Type[] declaredExceptionTypes, Set<String> alreadyDocumented,
        TagletWriter writer) {
    Content result = writer.getOutputInstance();
    //Add links to the exceptions declared but not documented.
    for (int i = 0; i < declaredExceptionTypes.length; i++) {
        if (declaredExceptionTypes[i].asClassDoc() != null &&
            ! alreadyDocumented.contains(
                    declaredExceptionTypes[i].asClassDoc().name()) &&
            ! alreadyDocumented.contains(
                declaredExceptionTypes[i].asClassDoc().qualifiedName())) {
            if (alreadyDocumented.size() == 0) {
                result.addContent(writer.getThrowsHeader());
            }
            result.addContent(writer.throwsTagOutput(declaredExceptionTypes[i]));
            alreadyDocumented.add(declaredExceptionTypes[i].asClassDoc().name());
        }
    }
    return result;
}
 

/**
 * Given an array of <code>Tag</code>s representing this custom
 * tag, return its string representation.
 * @param throwTags the array of <code>ThrowsTag</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 allowDups True if we allow duplicate throws tags to be documented.
 * @return the Content representation of this <code>Tag</code>.
 */
protected Content throwsTagsOutput(ThrowsTag[] throwTags,
    TagletWriter writer, Set<String> alreadyDocumented, boolean allowDups) {
    Content result = writer.getOutputInstance();
    if (throwTags.length > 0) {
        for (int i = 0; i < throwTags.length; ++i) {
            ThrowsTag tt = throwTags[i];
            ClassDoc cd = tt.exception();
            if ((!allowDups) && (alreadyDocumented.contains(tt.exceptionName()) ||
                (cd != null && alreadyDocumented.contains(cd.qualifiedName())))) {
                continue;
            }
            if (alreadyDocumented.size() == 0) {
                result.addContent(writer.getThrowsHeader());
            }
            result.addContent(writer.throwsTagOutput(tt));
            alreadyDocumented.add(cd != null ?
                cd.qualifiedName() : tt.exceptionName());
        }
    }
    return result;
}
 

/**
 * Given an array of <code>Tag</code>s representing this custom
 * tag, return its string representation.
 * @param throwTags the array of <code>ThrowsTag</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 allowDups True if we allow duplicate throws tags to be documented.
 * @return the Content representation of this <code>Tag</code>.
 */
protected Content throwsTagsOutput(ThrowsTag[] throwTags,
    TagletWriter writer, Set<String> alreadyDocumented, boolean allowDups) {
    Content result = writer.getOutputInstance();
    if (throwTags.length > 0) {
        for (int i = 0; i < throwTags.length; ++i) {
            ThrowsTag tt = throwTags[i];
            ClassDoc cd = tt.exception();
            if ((!allowDups) && (alreadyDocumented.contains(tt.exceptionName()) ||
                (cd != null && alreadyDocumented.contains(cd.qualifiedName())))) {
                continue;
            }
            if (alreadyDocumented.size() == 0) {
                result.addContent(writer.getThrowsHeader());
            }
            result.addContent(writer.throwsTagOutput(tt));
            alreadyDocumented.add(cd != null ?
                cd.qualifiedName() : tt.exceptionName());
        }
    }
    return result;
}
 

/**
 * 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(boolean isNonTypeParams,
        ParamTag[] paramTags, Map<String, String> rankMap, TagletWriter writer,
        Set<String> alreadyDocumented) {
    Content result = writer.getOutputInstance();
    if (paramTags.length > 0) {
        for (int i = 0; i < paramTags.length; ++i) {
            ParamTag pt = paramTags[i];
            String paramName = isNonTypeParams ?
                pt.parameterName() : "<" + pt.parameterName() + ">";
            if (! rankMap.containsKey(pt.parameterName())) {
                writer.getMsgRetriever().warning(pt.position(),
                    isNonTypeParams ?
                        "doclet.Parameters_warn" :
                        "doclet.Type_Parameters_warn",
                    paramName);
            }
            String rank = rankMap.get(pt.parameterName());
            if (rank != null && alreadyDocumented.contains(rank)) {
                writer.getMsgRetriever().warning(pt.position(),
                   isNonTypeParams ?
                       "doclet.Parameters_dup_warn" :
                       "doclet.Type_Parameters_dup_warn",
                   paramName);
            }
            result.addContent(processParamTag(isNonTypeParams, writer, pt,
                 pt.parameterName(), alreadyDocumented.size() == 0));
            alreadyDocumented.add(rank);
        }
    }
    return result;
}
 

/**
 * 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(boolean isNonTypeParams,
        TagletWriter writer, ParamTag paramTag, String name,
        boolean isFirstParam) {
    Content result = writer.getOutputInstance();
    String header = writer.configuration().getText(
        isNonTypeParams ? "doclet.Parameters" : "doclet.TypeParameters");
    if (isFirstParam) {
        result.addContent(writer.getParamHeader(header));
    }
    result.addContent(writer.paramTagOutput(paramTag,
        name));
    return result;
}
 

/**
 * This method adds a string content to the htmltree. If the last content member
 * added is a StringContent, append the string to that StringContent or else
 * create a new StringContent and add it to the html tree.
 *
 * @param stringContent string content that needs to be added
 */
public void addContent(String stringContent) {
    if (!content.isEmpty()) {
        Content lastContent = content.get(content.size() - 1);
        if (lastContent instanceof StringContent)
            lastContent.addContent(stringContent);
        else
            addContent(new StringContent(stringContent));
    }
    else
        addContent(new StringContent(stringContent));
}
 

@Override
protected void addReturnType(MethodDoc method, Content htmlTree) {
	htmlTree.addContent(this.writer.getSpace());
	htmlTree.addContent(Utils.getKeywords().getColonKeyword());
	htmlTree.addContent(" "); //$NON-NLS-1$
	super.addReturnType(method, htmlTree);
}
 

/**
 * {@inheritDoc}
 */
public Content getTagletOutput(Doc holder, TagletWriter writer)
        throws IllegalArgumentException {
    Content output = writer.getOutputInstance();
    Tag[] tags = holder.tags(getName());
    if (tags.length > 0) {
        String tagString = legacyTaglet.toString(tags);
        if (tagString != null) {
            output.addContent(new RawHtml(tagString));
        }
    }
    return output;
}
 

/**
 * 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(boolean isNonTypeParams,
        TagletWriter writer, ParamTag paramTag, String name,
        boolean isFirstParam) {
    Content result = writer.getOutputInstance();
    String header = writer.configuration().getText(
        isNonTypeParams ? "doclet.Parameters" : "doclet.TypeParameters");
    if (isFirstParam) {
        result.addContent(writer.getParamHeader(header));
    }
    result.addContent(writer.paramTagOutput(paramTag,
        name));
    return result;
}
 

public Content getTypeAnnotationLinks(LinkInfo linkInfo) {
    Content links = newContent();
    if (linkInfo.type.asAnnotatedType() == null)
        return links;
    AnnotationDesc[] annotations = linkInfo.type.asAnnotatedType().annotations();
    for (int i = 0; i < annotations.length; i++) {
        if (i > 0) {
            links.addContent(" ");
        }
        links.addContent(getTypeAnnotationLink(linkInfo, annotations[i]));
    }

    links.addContent(" ");
    return links;
}
 

/**
 * This method adds a string content to the htmltree. If the last content member
 * added is a StringContent, append the string to that StringContent or else
 * create a new StringContent and add it to the html tree.
 *
 * @param stringContent string content that needs to be added
 */
public void addContent(String stringContent) {
    if (!content.isEmpty()) {
        Content lastContent = content.get(content.size() - 1);
        if (lastContent instanceof StringContent)
            lastContent.addContent(stringContent);
        else
            addContent(new StringContent(stringContent));
    }
    else
        addContent(new StringContent(stringContent));
}
 

/**
 * 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(boolean isNonTypeParams,
        TagletWriter writer, ParamTag paramTag, String name,
        boolean isFirstParam) {
    Content result = writer.getOutputInstance();
    String header = writer.configuration().getText(
        isNonTypeParams ? "doclet.Parameters" : "doclet.TypeParameters");
    if (isFirstParam) {
        result.addContent(writer.getParamHeader(header));
    }
    result.addContent(writer.paramTagOutput(paramTag,
        name));
    return result;
}
 

/**
 * 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(boolean isNonTypeParams,
        TagletWriter writer, ParamTag paramTag, String name,
        boolean isFirstParam) {
    Content result = writer.getOutputInstance();
    String header = writer.configuration().getText(
        isNonTypeParams ? "doclet.Parameters" : "doclet.TypeParameters");
    if (isFirstParam) {
        result.addContent(writer.getParamHeader(header));
    }
    result.addContent(writer.paramTagOutput(paramTag,
        name));
    return result;
}
 

/**
 * 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(boolean isNonTypeParams,
        ParamTag[] paramTags, Map<String, String> rankMap, TagletWriter writer,
        Set<String> alreadyDocumented) {
    Content result = writer.getOutputInstance();
    if (paramTags.length > 0) {
        for (int i = 0; i < paramTags.length; ++i) {
            ParamTag pt = paramTags[i];
            String paramName = isNonTypeParams ?
                pt.parameterName() : "<" + pt.parameterName() + ">";
            if (! rankMap.containsKey(pt.parameterName())) {
                writer.getMsgRetriever().warning(pt.position(),
                    isNonTypeParams ?
                        "doclet.Parameters_warn" :
                        "doclet.Type_Parameters_warn",
                    paramName);
            }
            String rank = rankMap.get(pt.parameterName());
            if (rank != null && alreadyDocumented.contains(rank)) {
                writer.getMsgRetriever().warning(pt.position(),
                   isNonTypeParams ?
                       "doclet.Parameters_dup_warn" :
                       "doclet.Type_Parameters_dup_warn",
                   paramName);
            }
            result.addContent(processParamTag(isNonTypeParams, writer, pt,
                 pt.parameterName(), alreadyDocumented.size() == 0));
            alreadyDocumented.add(rank);
        }
    }
    return result;
}
 

/**
 * This method adds a string content to the htmltree. If the last content member
 * added is a StringContent, append the string to that StringContent or else
 * create a new StringContent and add it to the html tree.
 *
 * @param stringContent string content that needs to be added
 */
public void addContent(String stringContent) {
    if (!content.isEmpty()) {
        Content lastContent = content.get(content.size() - 1);
        if (lastContent instanceof StringContent)
            lastContent.addContent(stringContent);
        else
            addContent(new StringContent(stringContent));
    }
    else
        addContent(new StringContent(stringContent));
}
 

/**
 * 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(Doc holder, TagletWriter writer) {
    if (holder instanceof ExecutableMemberDoc) {
        ExecutableMemberDoc member = (ExecutableMemberDoc) holder;
        Content output = getTagletOutput(false, member, writer,
            member.typeParameters(), member.typeParamTags());
        output.addContent(getTagletOutput(true, member, writer,
            member.parameters(), member.paramTags()));
        return output;
    } else {
        ClassDoc classDoc = (ClassDoc) holder;
        return getTagletOutput(false, classDoc, writer,
            classDoc.typeParameters(), classDoc.typeParamTags());
    }
}
 

/** Build the link for the primitive.
 *
 * @param link the link.
 * @param linkInfo the information on the link.
 * @param type the type.
 */
@SuppressWarnings("static-method")
protected void getLinkForPrimitive(Content link, LinkInfo linkInfo, Type type) {
	link.addContent(type.typeName());
}