Support for @apiNote
This could also be used to add support for various other
missing block tags found in OpenJDK code.
e.g.
@since, @revised, @serialData, @author, @spec, @jls
Bug: 26624532
Change-Id: I0bb0896fcba176cbc2bdf469981ce0a80ba4e348
diff --git a/res/assets/templates/macros.cs b/res/assets/templates/macros.cs
index 16711c4..e7eb70c 100644
--- a/res/assets/templates/macros.cs
+++ b/res/assets/templates/macros.cs
@@ -126,7 +126,19 @@
/each ?><?cs
/def ?>
-<?cs # Show the short-form description of something. These come from shortDescr and deprecated ?><?cs
+<?cs # Print output for block tags that are not "standard" javadoc tags ?><?cs
+def:block_tag_list(tags) ?><?cs
+ each:tag = tags ?><?cs
+ if:tag.kind == "@apiNote" ?>
+ <div class="jd-tagdata">
+ <h5 class="jd-tagtitle">API Note:</h5>
+ <ul class="nolist"><li><?cs call:tag_list(tag.commentTags) ?></li></ul>
+ </div><?cs
+ /if ?><?cs
+ /each ?><?cs
+/def ?>
+
+<?cs # Show the short-form description of something. These come from shortDescr and deprecated ?><?cs
def:short_descr(obj) ?><?cs
if:subcount(obj.deprecated) ?><em><?cs
if:obj.deprecatedsince ?>
@@ -249,6 +261,9 @@
</ul>
</div><?cs
/if ?><?cs
+ if:subcount(obj.blockTags) ?>
+ <?cs call:block_tag_list(obj.blockTags) ?><?cs
+ /if ?><?cs
if:subcount(obj.paramTags) ?>
<div class="jd-tagdata">
<h5 class="jd-tagtitle">Parameters</h5>
diff --git a/src/com/google/doclava/Comment.java b/src/com/google/doclava/Comment.java
index 894bf04..225419d 100644
--- a/src/com/google/doclava/Comment.java
+++ b/src/com/google/doclava/Comment.java
@@ -28,6 +28,7 @@
Pattern.compile("((.*?)\\.)[ \t\r\n\\<](.*)", Pattern.DOTALL);
private static final Set<String> KNOWN_TAGS = new HashSet<String>(Arrays.asList(new String[] {
+ "@apiNote",
"@author",
"@since",
"@version",
@@ -362,6 +363,8 @@
mUndeprecateTagsList.add(new TextTagInfo("@undeprecate", "@undeprecate", text, pos));
} else if (name.equals("@include") || name.equals("@sample")) {
mInlineTagsList.add(new SampleTagInfo(name, "@include", text, mBase, pos));
+ } else if (name.equals("@apiNote")) {
+ mTagsList.add(new ParsedTagInfo(name, name, text, mBase, pos));
} else {
boolean known = KNOWN_TAGS.contains(name);
if (!known) {
@@ -430,6 +433,11 @@
return results.toArray(TagInfo.getArray(results.size()));
}
+ public TagInfo[] blockTags() {
+ init();
+ return mTags;
+ }
+
public ParamTagInfo[] paramTags() {
init();
return mParamTags;
@@ -528,6 +536,7 @@
mInitialized = true;
mInlineTags = mInlineTagsList.toArray(TagInfo.getArray(mInlineTagsList.size()));
+ mTags = mTagsList.toArray(TagInfo.getArray(mTagsList.size()));
mParamTags = mParamTagsList.toArray(ParamTagInfo.getArray(mParamTagsList.size()));
mSeeTags = mSeeTagsList.toArray(SeeTagInfo.getArray(mSeeTagsList.size()));
mThrowsTags = mThrowsTagsList.toArray(ThrowsTagInfo.getArray(mThrowsTagsList.size()));
@@ -539,6 +548,7 @@
mAttrTags = mAttrTagsList.toArray(AttrTagInfo.getArray(mAttrTagsList.size()));
mBriefTags = mBriefTagsList.toArray(TagInfo.getArray(mBriefTagsList.size()));
+ mTagsList = null;
mParamTagsList = null;
mSeeTagsList = null;
mThrowsTagsList = null;
diff --git a/src/com/google/doclava/MethodInfo.java b/src/com/google/doclava/MethodInfo.java
index 02157aa..0ea8c33 100644
--- a/src/com/google/doclava/MethodInfo.java
+++ b/src/com/google/doclava/MethodInfo.java
@@ -316,6 +316,10 @@
return new InlineTags();
}
+ public TagInfo[] blockTags() {
+ return comment().blockTags();
+ }
+
public InheritedTags firstSentenceTags() {
return new FirstSentenceTags();
}
@@ -581,6 +585,7 @@
TagInfo.makeHDF(data, base + ".shortDescr", firstSentenceTags());
TagInfo.makeHDF(data, base + ".descr", inlineTags());
+ TagInfo.makeHDF(data, base + ".blockTags", blockTags());
TagInfo.makeHDF(data, base + ".deprecated", deprecatedTags());
TagInfo.makeHDF(data, base + ".seeAlso", seeTags());
data.setValue(base + ".since", getSince());
diff --git a/src/com/google/doclava/ParsedTagInfo.java b/src/com/google/doclava/ParsedTagInfo.java
index aad3767..ded9522 100755
--- a/src/com/google/doclava/ParsedTagInfo.java
+++ b/src/com/google/doclava/ParsedTagInfo.java
@@ -16,6 +16,7 @@
package com.google.doclava;
+import com.google.clearsilver.jsilver.data.Data;
import java.util.ArrayList;
public class ParsedTagInfo extends TagInfo {
@@ -46,6 +47,12 @@
mCommentText = comment;
}
+ @Override
+ public void makeHDF(Data data, String base) {
+ super.makeHDF(data, base);
+ TagInfo.makeHDF(data, base + ".commentTags", commentTags());
+ }
+
public static <T extends ParsedTagInfo> TagInfo[] joinTags(T[] tags) {
ArrayList<TagInfo> list = new ArrayList<TagInfo>();
final int N = tags.length;
