com.sun.tools.doclets.internal.toolkit.Content Java Examples

/**
 * 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 (ThrowsTag tt : throwTags) {
            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;
}
 

/**
 * {@inheritDoc}
 */
@Override
public Content getTagletOutput(Doc doc, TagletWriter writer) throws IllegalArgumentException {
	Tag[] tags = doc.tags(getName());
	if (tags.length==0 && doc instanceof MethodDoc) { // inherit if necessary and possible
		final DocFinder.Output inheritedDoc = DocFinder.search(new DocFinder.Input((MethodDoc) doc, this));
		tags = inheritedDoc.holderTag == null ? tags : new Tag[] {inheritedDoc.holderTag};
	}
	if (tags.length==0)
		return null;
	final StringBuilder out = writeHeader(new StringBuilder());
	for(Tag tag : tags) { 
		writeTag(out, tag, writer);
	}
	return new RawHtml(out.toString());
}
 

/**
 * Inherit throws documentation for exceptions that were declared but not
 * documented.
 */
private Content inheritThrowsDocumentation(Doc holder,
        Type[] declaredExceptionTypes, Set<String> alreadyDocumented,
        TagletWriter writer) {
    Content result = writer.getOutputInstance();
    if (holder instanceof MethodDoc) {
        Set<Tag> declaredExceptionTags = new LinkedHashSet<Tag>();
        for (int j = 0; j < declaredExceptionTypes.length; j++) {
            DocFinder.Output inheritedDoc =
                DocFinder.search(new DocFinder.Input((MethodDoc) holder, this,
                    declaredExceptionTypes[j].typeName()));
            if (inheritedDoc.tagList.size() == 0) {
                inheritedDoc = DocFinder.search(new DocFinder.Input(
                    (MethodDoc) holder, this,
                    declaredExceptionTypes[j].qualifiedTypeName()));
            }
            declaredExceptionTags.addAll(inheritedDoc.tagList);
        }
        result.addContent(throwsTagsOutput(
            declaredExceptionTags.toArray(new ThrowsTag[] {}),
            writer, alreadyDocumented, false));
    }
    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;
}
 

/**
 * 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;
}
 

/**
 * {@inheritDoc}
 */
public Content getTagletOutput(Tag tag, TagletWriter writer) {
    FieldDoc field = getFieldDoc(
        writer.configuration(), tag, tag.text());
    if (field == null) {
        if (tag.text().isEmpty()) {
            //Invalid use of @value
            writer.getMsgRetriever().warning(tag.holder().position(),
                    "doclet.value_tag_invalid_use");
        } else {
            //Reference is unknown.
            writer.getMsgRetriever().warning(tag.holder().position(),
                    "doclet.value_tag_invalid_reference", tag.text());
        }
    } else if (field.constantValue() != null) {
        return writer.valueTagOutput(field,
            field.constantValueExpression(),
            ! field.equals(tag.holder()));
    } else {
        //Referenced field is not a constant.
        writer.getMsgRetriever().warning(tag.holder().position(),
            "doclet.value_tag_invalid_constant", field.name());
    }
    return writer.getOutputInstance();
}
 

/**
 * 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;
}
 

/**
 * Inherit throws documentation for exceptions that were declared but not
 * documented.
 */
private Content inheritThrowsDocumentation(Doc holder,
        Type[] declaredExceptionTypes, Set<String> alreadyDocumented,
        TagletWriter writer) {
    Content result = writer.getOutputInstance();
    if (holder instanceof MethodDoc) {
        Set<Tag> declaredExceptionTags = new LinkedHashSet<>();
        for (Type declaredExceptionType : declaredExceptionTypes) {
            DocFinder.Output inheritedDoc =
                    DocFinder.search(writer.configuration(), new DocFinder.Input((MethodDoc) holder, this,
                                                         declaredExceptionType.typeName()));
            if (inheritedDoc.tagList.size() == 0) {
                inheritedDoc = DocFinder.search(writer.configuration(), new DocFinder.Input(
                        (MethodDoc) holder, this,
                        declaredExceptionType.qualifiedTypeName()));
            }
            declaredExceptionTags.addAll(inheritedDoc.tagList);
        }
        result.addContent(throwsTagsOutput(
            declaredExceptionTags.toArray(new ThrowsTag[] {}),
            writer, alreadyDocumented, false));
    }
    return result;
}
 

@Override
public int charCount() {
    int n = 0;
    for (Content c : contents)
        n += c.charCount();
    return n;
}
 

/**
 * {@inheritDoc}
 */
public Content getTagletOutput(Tag tag, TagletWriter writer)
        throws IllegalArgumentException {
    Content output = writer.getOutputInstance();
    output.addContent(new RawHtml(legacyTaglet.toString(tag)));
    return output;
}
 

/**
 * Adds content for the HTML tag.
 *
 * @param tagContent tag content to be added
 */
public void addContent(Content tagContent) {
    if (tagContent instanceof ContentBuilder) {
        for (Content content: ((ContentBuilder)tagContent).contents) {
            addContent(content);
        }
    }
    else if (tagContent == HtmlTree.EMPTY || tagContent.isValid()) {
        if (content.isEmpty())
            content = new ArrayList<>();
        content.add(tagContent);
    }
}
 

/**
 * {@inheritDoc}
 */
@Override
public boolean write(Writer out, boolean atNewline) throws IOException {
    if (!isInline() && !atNewline)
        out.write(DocletConstants.NL);
    String tagString = htmlTag.toString();
    out.write("<");
    out.write(tagString);
    Iterator<HtmlAttr> iterator = attrs.keySet().iterator();
    HtmlAttr key;
    String value;
    while (iterator.hasNext()) {
        key = iterator.next();
        value = attrs.get(key);
        out.write(" ");
        out.write(key.toString());
        if (!value.isEmpty()) {
            out.write("=\"");
            out.write(value);
            out.write("\"");
        }
    }
    out.write(">");
    boolean nl = false;
    for (Content c : content)
        nl = c.write(out, nl);
    if (htmlTag.endTagRequired()) {
        out.write("</");
        out.write(tagString);
        out.write(">");
    }
    if (!isInline()) {
        out.write(DocletConstants.NL);
        return true;
    } else {
        return false;
    }
}
 

private Content createLambdaLabel(LinkInfoImpl linkInfo, Type[] arguments, int nParams) {
	final SARLFeatureAccess keywords = Utils.getKeywords();
	final Content content = newContent();
	content.addContent(keywords.getLeftParenthesisKeyword());
	boolean first = true;
	int i = 0;
	for (final Type parameterType : arguments) {
		if (first) {
			first = false;
		} else {
			content.addContent(","); //$NON-NLS-1$
		}
		content.addContent(getLink(new LinkInfoImpl(
				linkInfo.configuration, linkInfo.context,
				boundType(parameterType))));
		++i;
		if (i >= nParams) {
			break;
		}
	}
	content.addContent(keywords.getRightParenthesisKeyword());
	content.addContent(keywords.getEqualsSignGreaterThanSignKeyword());
	if (nParams >= arguments.length) {
		content.addContent(keywords.getVoidKeyword());
	} else {
		content.addContent(getLink(new LinkInfoImpl(
				linkInfo.configuration, linkInfo.context,
				boundType(arguments[arguments.length - 1]))));
	}
	return content;
}
 

/**
 * {@inheritDoc}
 */
public Content getTagletOutput(Doc holder, TagletWriter writer) {
    if (header == null || holder.tags(getName()).length == 0) {
        return null;
    }
    return writer.simpleTagOutput(holder.tags(getName()), header);
}
 

@Override
public boolean write(Writer writer, boolean atNewline) throws IOException {
    for (Content content: contents) {
        atNewline = content.write(writer, atNewline);
    }
    return atNewline;
}
 

/**
 * {@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;
}
 

/**
 * {@inheritDoc}
 */
@Override
public boolean write(Writer out, boolean atNewline) throws IOException {
    if (!isInline() && !atNewline)
        out.write(DocletConstants.NL);
    String tagString = htmlTag.toString();
    out.write("<");
    out.write(tagString);
    Iterator<HtmlAttr> iterator = attrs.keySet().iterator();
    HtmlAttr key;
    String value;
    while (iterator.hasNext()) {
        key = iterator.next();
        value = attrs.get(key);
        out.write(" ");
        out.write(key.toString());
        if (!value.isEmpty()) {
            out.write("=\"");
            out.write(value);
            out.write("\"");
        }
    }
    out.write(">");
    boolean nl = false;
    for (Content c : content)
        nl = c.write(out, nl);
    if (htmlTag.endTagRequired()) {
        out.write("</");
        out.write(tagString);
        out.write(">");
    }
    if (!isInline()) {
        out.write(DocletConstants.NL);
        return true;
    } else {
        return false;
    }
}
 

/**
 * Loop through each indivitual parameter.  It it does not have a
 * corresponding param tag, try to inherit it.
 */
private Content getInheritedTagletOutput(boolean isNonTypeParams, Doc holder,
        TagletWriter writer, Object[] formalParameters,
        Set<String> alreadyDocumented) {
    Content result = writer.getOutputInstance();
    if ((! alreadyDocumented.contains(null)) &&
            holder instanceof MethodDoc) {
        for (int i = 0; i < formalParameters.length; i++) {
            if (alreadyDocumented.contains(String.valueOf(i))) {
                continue;
            }
            //This parameter does not have any @param documentation.
            //Try to inherit it.
            DocFinder.Output inheritedDoc =
                DocFinder.search(new DocFinder.Input((MethodDoc) holder, this,
                    String.valueOf(i), ! isNonTypeParams));
            if (inheritedDoc.inlineTags != null &&
                    inheritedDoc.inlineTags.length > 0) {
                result.addContent(
                    processParamTag(isNonTypeParams, writer,
                        (ParamTag) inheritedDoc.holderTag,
                        isNonTypeParams ?
                            ((Parameter) formalParameters[i]).name():
                            ((TypeVariable) formalParameters[i]).typeName(),
                        alreadyDocumented.size() == 0));
            }
            alreadyDocumented.add(String.valueOf(i));
        }
    }
    return result;
}
 

@Override
public int charCount() {
    int n = 0;
    for (Content c : contents)
        n += c.charCount();
    return n;
}
 

/**
 * {@inheritDoc}
 */
public Content getTagletOutput(Tag tag, TagletWriter writer)
        throws IllegalArgumentException {
    Content output = writer.getOutputInstance();
    output.addContent(new RawHtml(legacyTaglet.toString(tag)));
    return output;
}
 

/**
 * 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 the <code>Tag</code> representation of this custom
 * tag, return its string representation, which is output
 * to the generated page.
 * @param tag the <code>Tag</code> representation of this custom tag.
 * @param tagletWriter the taglet writer for output.
 * @return the Content representation of this <code>Tag</code>.
 */
public Content getTagletOutput(Tag tag, TagletWriter tagletWriter) {
    if (! (tag.holder() instanceof ProgramElementDoc)) {
        return tagletWriter.getOutputInstance();
    }
    return tag.name().equals("@inheritDoc") ?
            retrieveInheritedDocumentation(tagletWriter, (ProgramElementDoc) tag.holder(), null, tagletWriter.isFirstSentence) :
            retrieveInheritedDocumentation(tagletWriter, (ProgramElementDoc) tag.holder(), tag, tagletWriter.isFirstSentence);
}
 

/**
 * {@inheritDoc}
 */
public Content getTagletOutput(Doc holder, TagletWriter writer) {
    if (header == null || holder.tags(getName()).length == 0) {
        return null;
    }
    return writer.simpleTagOutput(holder.tags(getName()), header);
}
 

/** Create the label for a function lambda.
 *
 * @param linkInfo the type.
 * @return the label.
 */
protected Content createFunctionLambdaLabel(LinkInfoImpl linkInfo) {
	final ParameterizedType type = linkInfo.type.asParameterizedType();
	if (type != null) {
		final Type[] arguments = type.typeArguments();
		if (arguments != null && arguments.length > 0) {
			return createLambdaLabel(linkInfo, arguments, arguments.length - 1);
		}
	}
	return linkInfo.label;
}
 

/**
 * 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());
    }
}
 

@Override
public boolean isEmpty() {
    for (Content content: contents) {
        if (!content.isEmpty())
            return false;
    }
    return true;
}
 

/**
 * {@inheritDoc}
 */
public Content getTagletOutput(Doc holder, TagletWriter writer) {
    SeeTag[] tags = holder.seeTags();
    if (tags.length == 0 && holder instanceof MethodDoc) {
        DocFinder.Output inheritedDoc =
            DocFinder.search(new DocFinder.Input((MethodDoc) holder, this));
        if (inheritedDoc.holder != null) {
            tags = inheritedDoc.holder.seeTags();
        }
    }
    return writer.seeTagOutput(holder, tags);
}
 

/**
 * Return the links to the type parameters.
 *
 * @param linkInfo     the information about the link to construct.
 * @param isClassLabel true if this is a class label.  False if it is
 *                     the type parameters portion of the link.
 * @return the links to the type parameters.
 */
public Content getTypeParameterLinks(LinkInfo linkInfo, boolean isClassLabel) {
    Content links = newContent();
    Type[] vars;
    if (linkInfo.executableMemberDoc != null) {
        vars = linkInfo.executableMemberDoc.typeParameters();
    } else if (linkInfo.type != null &&
            linkInfo.type.asParameterizedType() != null){
        vars =  linkInfo.type.asParameterizedType().typeArguments();
    } else if (linkInfo.classDoc != null){
        vars = linkInfo.classDoc.typeParameters();
    } else {
        //Nothing to document.
        return links;
    }
    if (((linkInfo.includeTypeInClassLinkLabel && isClassLabel) ||
         (linkInfo.includeTypeAsSepLink && ! isClassLabel)
          )
        && vars.length > 0) {
        links.addContent("<");
        for (int i = 0; i < vars.length; i++) {
            if (i > 0) {
                links.addContent(",");
            }
            links.addContent(getTypeParameterLink(linkInfo, vars[i]));
        }
        links.addContent(">");
    }
    return links;
}
 

/**
 * {@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;
}
 

/**
 * Given the <code>Tag</code> representation of this custom
 * tag, return its string representation, which is output
 * to the generated page.
 * @param tag the <code>Tag</code> representation of this custom tag.
 * @param tagletWriter the taglet writer for output.
 * @return the Content representation of this <code>Tag</code>.
 */
public Content getTagletOutput(Tag tag, TagletWriter tagletWriter) {
    if (! (tag.holder() instanceof ProgramElementDoc)) {
        return tagletWriter.getOutputInstance();
    }
    return tag.name().equals("@inheritDoc") ?
            retrieveInheritedDocumentation(tagletWriter, (ProgramElementDoc) tag.holder(), null, tagletWriter.isFirstSentence) :
            retrieveInheritedDocumentation(tagletWriter, (ProgramElementDoc) tag.holder(), tag, tagletWriter.isFirstSentence);
}