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

4 files changed, 38 insertions, 1 deletions

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 @@ def:tag_list(tags) ?><?cs
   /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 @@ def:description(obj) ?><?cs
       </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 @@ public class Comment {
       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 @@ public class Comment {
       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 @@ public class Comment {
     return results.toArray(TagInfo.getArray(results.size()));
   }
 
+  public TagInfo[] blockTags() {
+    init();
+    return mTags;
+  }
+
   public ParamTagInfo[] paramTags() {
     init();
     return mParamTags;
@@ -528,6 +536,7 @@ public class Comment {
     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 @@ public class Comment {
     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 @@ public class MethodInfo extends MemberInfo implements AbstractMethodInfo, Resolv
     return new InlineTags();
   }
 
+  public TagInfo[] blockTags() {
+    return comment().blockTags();
+  }
+
   public InheritedTags firstSentenceTags() {
     return new FirstSentenceTags();
   }
@@ -581,6 +585,7 @@ public class MethodInfo extends MemberInfo implements AbstractMethodInfo, Resolv
 
     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 @@ public class ParsedTagInfo extends TagInfo {
     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;