@Test
public void testTagRender() {
Doc mockDoc = mock(Doc.class);
Tag mockTag = mock(Tag.class);
String tagName = "tagName";
String tagText = "tagText";
String asciidoctorRenderedString = "rendered";
when(mockTag.name()).thenReturn(tagName);
when(mockTag.text()).thenReturn(tagText);
when(mockDoc.getRawCommentText()).thenReturn("input");
when(mockDoc.commentText()).thenReturn("input");
when(mockDoc.tags()).thenReturn(new Tag[] {mockTag});
when(mockAsciidoctor.render(eq("input"), argThat(new OptionsMatcher(false))))
.thenReturn("input");
when(mockAsciidoctor.render(eq(tagText), argThat(new OptionsMatcher(true))))
.thenReturn(asciidoctorRenderedString);
renderer.renderDoc(mockDoc);
verify(mockAsciidoctor).render(eq("input"), argThat(new OptionsMatcher(false)));
verify(mockAsciidoctor).render(eq(tagText), argThat(new OptionsMatcher(true)));
verify(mockDoc).setRawCommentText("input");
verify(mockDoc).setRawCommentText("input\n" + tagName + " " + asciidoctorRenderedString + "\n");
}
/**
* Reads the example file specified by the example tag of a doc member and adds it to the example
* section of the doc
*
* @param doc
* @throws IOException
*/
void setExample(Doc doc) throws IOException {
Tag[] exampleTag = doc.tags("@example");
if (exampleTag.length > 0) {
StringBuffer exampleBuffer = new StringBuffer();
FileReader in;
int c;
String[] pathComponents = exampleTag[0].text().split("/");
String filePath =
exampleTag[0].text() + "/" + pathComponents[pathComponents.length - 1] + ".pde";
in = new FileReader(new File(exampleFolder, filePath));
while ((c = in.read()) != -1) {
if ((char) c == '<') {
exampleBuffer.append("<");
} else {
exampleBuffer.append((char) c);
}
}
in.close();
String exampleString = exampleBuffer.toString();
EXAMPLE_TAG.setContent(exampleString);
} else {
EXAMPLE_TAG.setContent("None available");
}
}
public static Tag[] getTags(Doc doc, String tagName) {
Tag[] tags = doc.tags("@" + tagName);
if (tags != null && tags.length > 0) {
return tags;
}
return null;
}
/**
* Sets the usage for a doc item
*
* @param doc
*/
void setUsage(Doc doc) {
Tag[] usageTag = doc.tags("@usage");
if (usageTag.length > 0) {
USAGE_TAG.setContent(usageTag[0].text());
} else {
USAGE_TAG.setContent("Web & Application");
}
}
/**
* Return as a string the stereotypes associated with c terminated by the escape character term
*/
private void stereotype(Options opt, Doc c, Align align) {
for (Tag tag : c.tags("stereotype")) {
String t[] = StringUtil.tokenize(tag.text());
if (t.length != 1) {
System.err.println("@stereotype expects one field: " + tag.text());
continue;
}
tableLine(align, guilWrap(opt, t[0]));
}
}
public TagletOutput getTagletOutput(Doc holder, TagletWriter writer)
throws IllegalArgumentException {
TagletOutput out = writer.getTagletOutputInstance();
Tag[] tags = holder.tags(getName());
if (tags.length == 0) {
return null;
}
out.setOutput(toString(tags[0]));
return out;
}
public static void genTagOuput(
TagletManager tagletManager,
Doc doc,
Taglet[] taglets,
TagletWriter writer,
TagletOutput output,
Set<String> tagletsToPrint) {
tagletManager.checkTags(doc, doc.tags(), false);
tagletManager.checkTags(doc, doc.inlineTags(), true);
TagletOutput currentOutput = null;
for (int i = 0; i < taglets.length; i++) {
if (!tagletsToPrint.contains(taglets[i].getName())) continue;
if (doc instanceof ClassDoc && taglets[i] instanceof ParamTaglet) {
// The type parameters are documented in a special section away
// from the tag info, so skip here.
continue;
}
if (taglets[i] instanceof DeprecatedTaglet) {
// Deprecated information is documented "inline", not in tag
// info
// section.
continue;
}
try {
currentOutput = taglets[i].getTagletOutput(doc, writer);
} catch (IllegalArgumentException e) {
// The taglet does not take a member as an argument. Let's try
// a single tag.
Tag[] tags = doc.tags(taglets[i].getName());
if (tags.length > 0) {
currentOutput = taglets[i].getTagletOutput(tags[0], writer);
}
}
if (currentOutput != null) {
tagletManager.seenCustomTag(taglets[i].getName());
output.appendOutput(currentOutput);
}
}
}
/**
* Return as a string the tagged values associated with c
*
* @param opt the Options used to guess font names
* @param c the Doc entry to look for @tagvalue
* @param prevterm the termination string for the previous element
* @param term the termination character for each tagged value
*/
private void tagvalue(Options opt, Doc c) {
Tag tags[] = c.tags("tagvalue");
if (tags.length == 0) return;
for (Tag tag : tags) {
String t[] = StringUtil.tokenize(tag.text());
if (t.length != 2) {
System.err.println("@tagvalue expects two fields: " + tag.text());
continue;
}
tableLine(Align.RIGHT, "{" + t[0] + " = " + t[1] + "}", opt, Font.TAG);
}
}
/**
* Return true if the given Doc should be included in the serialized form.
*
* @param doc the Doc object to check for serializability.
*/
private static boolean serialDocInclude(Doc doc) {
if (doc.isEnum()) {
return false;
}
Tag[] serial = doc.tags("serial");
if (serial.length > 0) {
String serialtext = StringUtils.toLowerCase(serial[0].text());
if (serialtext.indexOf("exclude") >= 0) {
return false;
} else if (serialtext.indexOf("include") >= 0) {
return true;
}
}
return true;
}
@Test
public void testAtLiteralRender() {
Doc mockDoc = mock(Doc.class);
String convertedText = "Test";
String rawText = "@" + convertedText;
when(mockDoc.getRawCommentText()).thenReturn(rawText);
when(mockDoc.commentText()).thenReturn("input");
when(mockDoc.tags()).thenReturn(new Tag[] {});
when(mockAsciidoctor.render(anyString(), any(Options.class))).thenReturn("input");
renderer.renderDoc(mockDoc);
verify(mockDoc).setRawCommentText("{@literal @}" + convertedText);
verify(mockAsciidoctor).render(anyString(), any(Options.class));
}
/**
* Return true if the given Doc is deprecated.
*
* @param doc the Doc to check.
* @return true if the given Doc is deprecated.
*/
public static boolean isDeprecated(Doc doc) {
if (doc.tags("deprecated").length > 0) {
return true;
}
AnnotationDesc[] annotationDescList;
if (doc instanceof PackageDoc) annotationDescList = ((PackageDoc) doc).annotations();
else annotationDescList = ((ProgramElementDoc) doc).annotations();
for (int i = 0; i < annotationDescList.length; i++) {
if (annotationDescList[i]
.annotationType()
.qualifiedName()
.equals(java.lang.Deprecated.class.getName())) {
return true;
}
}
return false;
}
protected void printIndexComment(Doc member, Tag[] firstSentenceTags) {
Tag[] deprs = member.tags("deprecated");
if (Util.isDeprecated((ProgramElementDoc) member)) {
boldText("doclet.Deprecated");
space();
if (deprs.length > 0) {
printInlineDeprecatedComment(member, deprs[0]);
}
return;
} else {
ClassDoc cd = ((ProgramElementDoc) member).containingClass();
if (cd != null && Util.isDeprecated(cd)) {
boldText("doclet.Deprecated");
space();
}
}
printSummaryComment(member, firstSentenceTags);
}
/** {@inheritDoc} */
public Content deprecatedTagOutput(Doc doc) {
ContentBuilder result = new ContentBuilder();
Tag[] deprs = doc.tags("deprecated");
if (doc instanceof ClassDoc) {
if (Util.isDeprecated((ProgramElementDoc) doc)) {
result.addContent(
HtmlTree.SPAN(
HtmlStyle.deprecatedLabel,
new StringContent(configuration.getText("doclet.Deprecated"))));
result.addContent(RawHtml.nbsp);
if (deprs.length > 0) {
Tag[] commentTags = deprs[0].inlineTags();
if (commentTags.length > 0) {
result.addContent(commentTagsToOutput(null, doc, deprs[0].inlineTags(), false));
}
}
}
} else {
MemberDoc member = (MemberDoc) doc;
if (Util.isDeprecated((ProgramElementDoc) doc)) {
result.addContent(
HtmlTree.SPAN(
HtmlStyle.deprecatedLabel,
new StringContent(configuration.getText("doclet.Deprecated"))));
result.addContent(RawHtml.nbsp);
if (deprs.length > 0) {
Content body = commentTagsToOutput(null, doc, deprs[0].inlineTags(), false);
if (!body.isEmpty()) result.addContent(HtmlTree.SPAN(HtmlStyle.deprecationComment, body));
}
} else {
if (Util.isDeprecated(member.containingClass())) {
result.addContent(
HtmlTree.SPAN(
HtmlStyle.deprecatedLabel,
new StringContent(configuration.getText("doclet.Deprecated"))));
result.addContent(RawHtml.nbsp);
}
}
}
return result;
}
@Test
public void testParamTagWithTypeParameter() {
String commentText = "comment";
String param1Name = "T";
String param1Desc = "";
String param1Text = "<" + param1Name + ">";
String param2Name = "X";
String param2Desc = "description";
String param2Text = "<" + param2Name + "> " + param2Desc;
String sourceText = commentText + "\n@param " + param1Text + "\n@param " + param2Text;
Doc mockDoc = mock(Doc.class);
when(mockDoc.getRawCommentText()).thenReturn(sourceText);
when(mockDoc.commentText()).thenReturn(commentText);
Tag[] tags = new Tag[2];
ParamTag mockTag1 = mock(ParamTag.class);
when(mockTag1.name()).thenReturn("@param");
when(mockTag1.isTypeParameter()).thenReturn(true);
when(mockTag1.parameterName()).thenReturn(param1Name);
when(mockTag1.parameterComment()).thenReturn(param1Desc);
tags[0] = mockTag1;
ParamTag mockTag2 = mock(ParamTag.class);
when(mockTag2.name()).thenReturn("@param");
when(mockTag2.isTypeParameter()).thenReturn(true);
when(mockTag2.parameterName()).thenReturn(param2Name);
when(mockTag2.parameterComment()).thenReturn(param2Desc);
tags[1] = mockTag2;
when(mockDoc.tags()).thenReturn(tags);
when(mockAsciidoctor.render(eq(commentText), any(Options.class))).thenReturn(commentText);
when(mockAsciidoctor.render(eq(param2Desc), any(Options.class))).thenReturn(param2Desc);
renderer.renderDoc(mockDoc);
verify(mockAsciidoctor).render(eq(commentText), argThat(new OptionsMatcher(false)));
verify(mockAsciidoctor).render(eq(param2Desc), argThat(new OptionsMatcher(true)));
// fixture step
verify(mockDoc).setRawCommentText(eq(sourceText));
// result step
verify(mockDoc).setRawCommentText(eq(sourceText));
}
/**
* Adds all related members of a doc item to the related section of the doc
*
* @param doc
*/
void addRelatedmember(
Doc doc, HashMap<String, String> fieldLinks, HashMap<String, String> methodLinks) {
Tag[] relatedTags = doc.tags("@related");
for (Tag relatedTag : relatedTags) {
String link = "";
if (fieldLinks.containsKey(relatedTag.text())) {
link = fieldLinks.get(relatedTag.text());
} else if (methodLinks.containsKey(relatedTag.text())) {
link = methodLinks.get(relatedTag.text());
} else if (StartDoclet.classLinks.containsKey(relatedTag.text())) {
link = StartDoclet.classLinks.get(relatedTag.text());
} else {
System.out.println("No related member found for @related " + relatedTag.text());
}
StringBuffer relatedBuffer = new StringBuffer();
relatedBuffer.append("<A href=\"");
relatedBuffer.append(link);
relatedBuffer.append(".html\">");
relatedBuffer.append(relatedTag.text());
relatedBuffer.append("</A><BR>\n");
RELATED_TAG.addContent(relatedBuffer.toString());
}
}
/** Checks if the package javadoc contains @ArchitectureDocument tag */
private boolean containsArchDocTag(Doc doc) {
for (Tag tag : doc.tags()) {
if (tag.name().equals("@ArchitectureDocument")) return true;
}
return false;
}
public Tag[] getTags() {
return Tag.convert(mRootDoc, mDoc.tags());
}
/**
* Return true if the doc element is getting documented, depending upon -nodeprecated option
* and @deprecated tag used. Return true if -nodeprecated is not used or @deprecated tag is not
* used.
*/
public boolean isGeneratedDoc(Doc doc) {
if (!nodeprecated) {
return true;
}
return (doc.tags("deprecated")).length == 0;
}
private static boolean isExcluded(Doc doc) {
return doc.tags("exclude").length != 0;
}
/** Overrides {@link HtmlStandardWriter#generateTagInfo} to include Plugged In's tags. */
public void generateTagInfo(Doc doc) {
Tag[] sinces = doc.tags("since");
Tag[] sees = doc.seeTags();
Tag[] authors;
Tag[] versions;
Tag[] copyrights;
Tag[] createds;
Tag[] modifieds;
Tag[] licences;
if (configuration.showauthor) {
authors = doc.tags("author");
} else {
authors = new Tag[0];
}
if (configuration.showversion) {
versions = doc.tags("version");
} else {
versions = new Tag[0];
}
if (configuration.nosince) {
sinces = new Tag[0];
}
copyrights = doc.tags("copyright");
createds = doc.tags("created");
licences = doc.tags("licence");
modifieds = doc.tags("modified");
if (sinces.length > 0
|| sees.length > 0
|| authors.length > 0
|| versions.length > 0
|| copyrights.length > 0
|| createds.length > 0
|| licences.length > 0
|| modifieds.length > 0
|| (doc.isClass() && ((ClassDoc) doc).isSerializable())) {
dl();
printSinceTag(doc);
if (versions.length > 0) {
// There is going to be only one Version tag.
dt();
boldText("doclet.Version");
dd();
printInlineComment(versions[0]);
ddEnd();
}
if (authors.length > 0) {
dt();
boldText("doclet.Author");
dd();
for (int i = 0; i < authors.length; ++i) {
if (i > 0) {
print(", ");
}
printInlineComment(authors[i]);
}
ddEnd();
}
if (createds.length > 0) {
// There is going to be only one Created tag.
dt();
write("<b>Created:</b>");
dd();
printInlineComment(createds[0]);
ddEnd();
}
if (modifieds.length > 0) {
dt();
write("<b>Modified:</b>");
dd();
for (int i = 0; i < modifieds.length; ++i) {
if (i > 0) {
print(", ");
}
printInlineComment(modifieds[i]);
}
ddEnd();
}
if (copyrights.length > 0) {
dt();
write("<b>Copyright:</b>");
dd();
for (int i = 0; i < copyrights.length; ++i) {
if (i > 0) {
print(", ");
}
printInlineComment(copyrights[i]);
}
ddEnd();
}
if (licences.length > 0) {
// There is going to be only one Licence tag.
dt();
write("<b>Licence:</b>");
dd();
printInlineComment(licences[0]);
ddEnd();
}
// printSeeTags(doc); // This method vanished in 1.4 beta 3
dlEnd();
}
}