/** {@inheritDoc} */
public Content getTagletOutput(Tag tag, TagletWriter writer) {
ArrayList inlineTags = new ArrayList();
inlineTags.add(new TextTag(tag.holder(), "<b>"));
inlineTags.addAll(Arrays.asList(tag.inlineTags()));
inlineTags.add(new TextTag(tag.holder(), "</b>"));
return writer.commentTagsToOutput(tag, (Tag[]) inlineTags.toArray(new Tag[] {}));
}
@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");
}
public static String findParamText(Tag[] tags, String name) {
for (Tag tag : tags)
if (tag.text().trim().equals(name) || tag.text().trim().startsWith(name + " "))
return tag.text().trim().substring(name.length()).trim();
return null;
}
private Tag getTag(MethodDoc methodDoc, final String tagName) {
for (Tag tag : methodDoc.tags()) {
if (tagName.equals(tag.name())) {
return tag;
}
}
return null;
}
public static String firstSentence(Doc doc) {
Tag[] tags = doc.firstSentenceTags();
StringBuilder sb = new StringBuilder();
if (!isEmpty(tags)) {
for (Tag tag : tags) sb.append(tag.text());
}
return sb.toString();
}
private Tag[] getTags(String kind) {
List<Tag> result = new ArrayList<Tag>();
for (Tag t : blockTags) {
if (t.kind().equals(kind)) {
result.add(t);
}
}
return result.toArray(new X10Tag[0]);
}
/**
* 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 TagletOutput representation of this <code>Tag</code>.
*/
public TagletOutput getTagletOutput(Tag tag, TagletWriter tagletWriter) {
if (!(tag.holder() instanceof MethodDoc)) {
return tagletWriter.getOutputInstance();
}
return tag.name().equals("@inheritDoc")
? retrieveInheritedDocumentation(
tagletWriter, (MethodDoc) tag.holder(), null, tagletWriter.isFirstSentence)
: retrieveInheritedDocumentation(
tagletWriter, (MethodDoc) tag.holder(), tag, tagletWriter.isFirstSentence);
}
public void processMethodDoc(MethodDoc methodDoc, MethodDocType methodDocType) {
final String tagName = "@example.tag";
final Tag exampleTag = getTag(methodDoc, tagName);
if (exampleTag != null) {
final MyNamedValueType namedValueType = new MyNamedValueType();
namedValueType.setName(EXAMPLE_TAG);
namedValueType.setValue(exampleTag.text());
methodDocType.getAny().add(namedValueType);
}
}
/**
* 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]));
}
}
private List<? extends BodyElement> resolveImgTag(Context context, Tag tag) {
File source = tag.position().file().getParentFile();
String path = tag.text();
try {
File target = new File(source, path).getCanonicalFile();
return Collections.singletonList(new ImageImpl(tag, target));
} catch (Exception ex) {
return null;
}
}
/**
* 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);
}
}
/** {@inheritDoc} */
public Content simpleTagOutput(Tag simpleTag, String header) {
ContentBuilder result = new ContentBuilder();
result.addContent(HtmlTree.DT(HtmlTree.SPAN(HtmlStyle.simpleTagLabel, new RawHtml(header))));
Content body = htmlWriter.commentTagsToContent(simpleTag, null, simpleTag.inlineTags(), false);
result.addContent(HtmlTree.DD(body));
return result;
}
private void printIncludes() {
MethodDoc javaDoc = method.getJavaDoc();
Tag[] includes = Utils.getTags(javaDoc, "include");
if (includes == null) return;
File relativeTo = javaDoc.containingClass().position().file().getParentFile();
for (Tag include : includes) {
String fileName = include.text();
File file = new File(relativeTo, fileName);
if (!file.exists()) {
doclet.printError(include.position(), "Missing included file: " + fileName);
continue;
}
String text = Utils.readResource(file);
print(text);
}
}
/**
* Given a <code>MethodDoc</code> item, a <code>Tag</code> in the <code>MethodDoc</code> item and
* a String, replace all occurrences of @inheritDoc with documentation from it's superclass or
* superinterface.
*
* @param writer the writer that is writing the output.
* @param md the {@link MethodDoc} that we are documenting.
* @param holderTag the tag that holds the inheritDoc tag.
* @param isFirstSentence true if we only want to inherit the first sentence.
*/
private TagletOutput retrieveInheritedDocumentation(
TagletWriter writer, MethodDoc md, Tag holderTag, boolean isFirstSentence) {
TagletOutput replacement = writer.getTagletOutputInstance();
Configuration configuration = writer.configuration();
Taglet inheritableTaglet =
holderTag == null ? null : configuration.tagletManager.getTaglet(holderTag.name());
if (inheritableTaglet != null && !(inheritableTaglet instanceof InheritableTaglet)) {
// This tag does not support inheritence.
configuration.message.warning(
md.position(), "doclet.noInheritedDoc", md.name() + md.flatSignature());
}
DocFinder.Output inheritedDoc =
DocFinder.search(
new DocFinder.Input(
md, (InheritableTaglet) inheritableTaglet, holderTag, isFirstSentence, true));
if (inheritedDoc.isValidInheritDocTag == false) {
configuration.message.warning(
md.position(), "doclet.noInheritedDoc", md.name() + md.flatSignature());
} else if (inheritedDoc.inlineTags.length > 0) {
replacement =
writer.commentTagsToOutput(
inheritedDoc.holderTag,
inheritedDoc.holder,
inheritedDoc.inlineTags,
isFirstSentence);
}
return replacement;
}
private HttpStatusCode(Tag tag) {
// Split on whitespace
String[] tagParts = tag.text().split("\\s+");
statusCode = Integer.parseInt(tagParts[0]);
tagParts = Arrays.copyOfRange(tagParts, 1, tagParts.length, String[].class);
description = StringUtils.join(tagParts, " ");
}
/**
* Given the <code>Tag</code> representation of this custom tag, return its string representation.
*
* @param tag the <code>Tag</code> representation of this custom tag.
*/
public String toString(Tag tag) {
return "<DT><B>"
+ HEADER
+ "</B><DD>"
+ "<table cellpadding=2 cellspacing=0><tr><td bgcolor=\"yellow\">"
+ tag.text()
+ "</td></tr></table></DD>\n";
}
/** {@inheritDoc} */
public Content propertyTagOutput(Tag tag, String prefix) {
Content body = new ContentBuilder();
body.addContent(new RawHtml(prefix));
body.addContent(" ");
body.addContent(HtmlTree.CODE(new RawHtml(tag.text())));
body.addContent(".");
Content result = HtmlTree.P(body);
return result;
}
public List<? extends BodyElement> resolve(Context context) {
List<? extends BodyElement> resolved = null;
Tag tag = getTag();
if (tag instanceof SeeTag) {
SeeTag seeTag = (SeeTag) tag;
resolved = resolveSeeTag(context, seeTag);
} else if (tag.name().equals("@img")) {
resolved = resolveImgTag(context, tag);
}
if (resolved != null) {
return resolved;
}
System.err.println(
ArticleUtil.makeConsoleLink("Unresolved link " + tag + " in ", tag.position()));
return Collections.singletonList(this);
}
/** {@inheritDoc} */
public Content returnTagOutput(Tag returnTag) {
ContentBuilder result = new ContentBuilder();
result.addContent(
HtmlTree.DT(
HtmlTree.SPAN(
HtmlStyle.returnLabel,
new StringContent(configuration.getText("doclet.Returns")))));
result.addContent(
HtmlTree.DD(
htmlWriter.commentTagsToContent(returnTag, null, returnTag.inlineTags(), false)));
return result;
}
/**
* Given the <code>Tag</code> representation of this custom tag, return its string representation.
*
* @param tag the <code>Tag</code> representation of this custom tag.
* @return The string representation.
*/
@Override
public String toString(Tag tag) {
String color = tag.text();
// Assume the first thing on the line is the color.
int spaceIndex = color.indexOf(' ');
if (spaceIndex != -1) {
// Deal with the fact that somebody might just have put a
// color.
color = color.substring(0, spaceIndex);
}
return "<DT><B>"
+ _tagName
+ ":</B><DD>"
+ "<table cellpadding=2 cellspacing=0><tr><td bgcolor=\""
+ color.toLowerCase()
+ "\">"
+ tag.text()
+ "</td></tr></table></DD>\n";
}
public void addGuardTags(List<X10Tag> list) {
StringBuilder sb = new StringBuilder();
Tag[] tags = tags(X10Tag.GUARD);
if (tags.length > 0) {
sb.append("<DL><DT><B>Guard:</B>");
for (Tag tag : tags) {
sb.append("<DD><CODE>");
String code = tag.text();
String tokens[] = code.split("\\s");
if (tokens.length > 1) {
sb.append(tokens[0]);
sb.append("</CODE> - ");
sb.append(code.replace(tokens[0], "").trim());
} else {
sb.append("</CODE>");
}
}
sb.append("</DL><P>");
}
list.addAll(createInlineTags(sb.toString(), this));
}
private RestMethod(MethodDoc doc) {
this.httpStatusCodes = new ArrayList<HttpStatusCode>();
for (Tag tag : doc.tags(RETURN_CODE_TAG)) {
this.httpStatusCodes.add(new HttpStatusCode(tag));
}
for (Tag tag : doc.tags(DEPRECATED_TAG)) {
this.deprecated = tag.text();
}
for (Tag tag : doc.tags(RETURN_TAG)) {
this.returns = tag.text();
}
this.method = doc.qualifiedName();
String[] parts = doc.commentText().split("\n\n");
this.summary = parts[0];
if (parts.length > 1) {
this.description = parts[1];
}
}
/**
* 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());
}
}
public String toString(Tag tag) {
return "<dt title=\"The FLAP channel on which this command resides on "
+ "a normal OSCAR connection\"><b>FLAP channel:</b></dt><dd>"
+ tag.text()
+ "</dd>";
}
/** {@inheritDoc} */
protected Content codeTagOutput(Tag tag) {
Content result = HtmlTree.CODE(new StringContent(Util.normalizeNewlines(tag.text())));
return result;
}
/**
* Parses a method type definition
*
* @param docMethod
* @return
*/
protected static Method ParseMethod(MethodDoc docMethod) {
assert (docMethod != null);
Method xmlMethod = new Method();
xmlMethod.name = docMethod.name();
xmlMethod.hash = computeHash(docMethod.qualifiedName(), docMethod.signature());
xmlMethod.qualifiedName = docMethod.qualifiedName();
xmlMethod.comment = docMethod.commentText();
xmlMethod.signature = docMethod.signature();
xmlMethod.isNative = docMethod.isNative();
xmlMethod.isVarArgs = docMethod.isVarArgs();
xmlMethod.isSynchronized = docMethod.isSynchronized();
xmlMethod.isFinal = docMethod.isFinal();
xmlMethod.isAbstract = docMethod.isAbstract();
xmlMethod.isStatic = docMethod.isStatic();
xmlMethod.scope = DetermineScope(docMethod);
// Parse parameters of the method
Parameter[] parameters = docMethod.parameters();
if (parameters != null && parameters.length > 0) {
ParamTag[] paramComments = docMethod.paramTags();
ArrayList<Param> paramList = new ArrayList<Param>();
for (Parameter parameter : parameters) {
ParamTag paramComment = null;
// look to see if this parameter has comments
// if so, paramComment will be set
for (ParamTag testParam : paramComments) {
String testParamName = testParam.parameterName();
if (testParamName != null) {
if (testParamName.compareTo(parameter.name()) == 0) {
paramComment = testParam;
break;
}
}
}
paramList.add(ParseParameter(parameter, paramComment));
}
xmlMethod.parameters = paramList.toArray(new Param[] {});
} else {
log.debug("No parameters for method: " + docMethod.name());
}
// Parse result data
Result returnInfo = new Result();
Tag[] returnTags = docMethod.tags("@return");
if (returnTags != null && returnTags.length > 0) {
// there should be only one return tag. but heck,
// if they specify two, so what...
StringBuilder builder = new StringBuilder();
for (Tag returnTag : returnTags) {
String returnTagText = returnTag.text();
if (returnTagText != null) {
builder.append(returnTagText);
builder.append("\n");
}
}
returnInfo.comment = builder.substring(0, builder.length() - 1);
}
returnInfo.type = ParseType(docMethod.returnType());
xmlMethod.result = returnInfo;
// Parse exceptions of the method
Type[] types = docMethod.thrownExceptionTypes();
ThrowsTag[] exceptionComments = docMethod.throwsTags();
if (types != null && types.length > 0) {
ArrayList<ExceptionInstance> exceptionList = new ArrayList<ExceptionInstance>();
for (Type exceptionType : types) {
ExceptionInstance exception = new ExceptionInstance();
exception.type = ParseType(exceptionType);
for (ThrowsTag exceptionComment : exceptionComments) {
if (exceptionType == exceptionComment.exceptionType()) {
exception.comment = exceptionComment.exceptionComment();
ClassDoc exceptionDetails = exceptionComment.exception();
// not yet parsing Exceptions defined within the supplied code set
exception.type = ParseType(exceptionComment.exceptionType());
break;
}
}
exceptionList.add(exception);
}
xmlMethod.exceptions = exceptionList.toArray(new ExceptionInstance[] {});
}
// parse annotations from the method
xmlMethod.annotationInstances =
ParseAnnotationInstances(docMethod.annotations(), docMethod.qualifiedName());
return xmlMethod;
}
/** Override to include RCS keyword substitution. */
public void printInlineComment(Tag tag) {
String text = tag.text();
text = replaceRcsKeywords(text);
text = replaceDocRootDir(text);
print(text);
}
@Override
public String toString(Tag tag) {
return "<DT><B>PRE:</B></DT><DD>" + tag.text() + "</DD>";
}
/**
* Given the <code>Tag</code> representation of this custom tag, return its string representation.
*
* @param tag the <code>Tag</code> representation of this custom tag.
*/
public String toString(Tag tag) {
return (format(tag.text()));
}
/**
* Print all relations for a given's class's tag
*
* @param tagname the tag containing the given relation
* @param from the source class
* @param edgetype the dot edge specification
*/
private void allRelation(Options opt, RelationType rt, ClassDoc from) {
String tagname = rt.toString().toLowerCase();
for (Tag tag : from.tags(tagname)) {
String t[] = StringUtil.tokenize(tag.text()); // l-src label l-dst target
if (t.length != 4) {
System.err.println(
"Error in "
+ from
+ "\n"
+ tagname
+ " expects four fields (l-src label l-dst target): "
+ tag.text());
return;
}
ClassDoc to = from.findClass(t[3]);
if (to != null) {
if (hidden(to)) continue;
relation(opt, rt, from, to, t[0], t[1], t[2]);
} else {
if (hidden(t[3])) continue;
relation(opt, rt, from, from.toString(), to, t[3], t[0], t[1], t[2]);
}
}
}
