Update doclava to use @since tags from comments.

Metalava is now generating the API stubs and handles the calculation
of when APIs were introduced and deprecated. It now directly adds this
info to each APIs comment using the tags @apiSince and
@deprecatedSince.

This cl enables the doclava API reference generator to extract these
tags and output them to the docs. Requires passing -metalavaApiSince
into the doclava build.

bug: 125939989
Test: make ds-docs

Change-Id: I1a6c04a3e05dd1dc74ccdaf81ec45b52a40f55fc

6 files changed, 79 insertions, 29 deletions

diff --git a/res/assets/templates-sdk/page_info.cs b/res/assets/templates-sdk/page_info.cs
index 8585ee1..5fe6f7b 100644
--- a/res/assets/templates-sdk/page_info.cs
+++ b/res/assets/templates-sdk/page_info.cs
@@ -27,13 +27,6 @@ elif:subcount(class)
   <?cs if:class.artifact ?>
     <br><?cs call:artifact_tags(class) ?>
   <?cs /if ?>
-  <?cs if:class.deprecatedsince ?><?cs
-    if:class.artifact ?><br>Deprecated since version <?cs var:class.deprecatedsince ?><?cs
-    else ?><br>Deprecated since
-    <a href="<?cs var:toroot ?>guide/topics/manifest/uses-sdk-element.html#ApiLevels">API level
-      <?cs var:class.deprecatedsince ?></a><?cs
-    /if ?>
-  <?cs /if ?>
   <?cs call:federated_refs(class) ?>
 </div>
 
diff --git a/res/assets/templates/macros.cs b/res/assets/templates/macros.cs
index 13a884f..db502bb 100644
--- a/res/assets/templates/macros.cs
+++ b/res/assets/templates/macros.cs
@@ -267,17 +267,24 @@ def:see_also_tags(also) ?><?cs
 def:since_tags(obj) ?><?cs
 if:reference.apilevels && obj.since ?><?cs
   if:string.slice(obj.since,0,1) > 0 ?>
-    added in <?cs
+    Added in <?cs
       if:string.find(obj.since,'.') > -1
         ?><a href="<?cs var:toroot ?>topic/libraries/support-library/revisions.html">version<?cs
       else
         ?><a href="<?cs var:toroot ?>guide/topics/manifest/uses-sdk-element.html#ApiLevels">API level<?cs
       /if ?> <?cs
     var:obj.since ?></a><?cs
-  else ?>
-    <b><a href="<?cs var:toroot ?>preview/">Android <?cs var:obj.since ?> Developer Preview</a></b><?cs
+  else ?><a data-version-added="<?cs var:obj.since ?>" href="<?cs var:toroot ?>preview/"><b>Added in Android <?cs
+    var:obj.since ?></b></a><?cs
   /if?><?cs
-/if ?><?cs
+/if ?>
+  <?cs if:obj.deprecatedsince ?><?cs
+    if:class.artifact ?><br>Deprecated in version <?cs var:obj.deprecatedsince ?><?cs
+    else ?><br>Deprecated in
+    <a href="<?cs var:toroot ?>guide/topics/manifest/uses-sdk-element.html#ApiLevels">API level
+      <?cs var:obj.deprecatedsince ?></a><?cs
+    /if ?>
+  <?cs /if ?><?cs
 /def ?><?cs
 
 # print the artifact ?><?cs
diff --git a/src/com/google/doclava/ClassInfo.java b/src/com/google/doclava/ClassInfo.java
index dbe7783..2a5db75 100644
--- a/src/com/google/doclava/ClassInfo.java
+++ b/src/com/google/doclava/ClassInfo.java
@@ -39,7 +39,6 @@ import java.util.TreeMap;
 import java.util.function.Predicate;
 
 public class ClassInfo extends DocInfo implements ContainerInfo, Comparable, Scoped, Resolvable {
-
   /**
    * Contains a ClassInfo and a TypeInfo.
    * <p>
diff --git a/src/com/google/doclava/Comment.java b/src/com/google/doclava/Comment.java
index 63ace55..e11e329 100644
--- a/src/com/google/doclava/Comment.java
+++ b/src/com/google/doclava/Comment.java
@@ -30,9 +30,14 @@ public class Comment {
   private static final Set<String> KNOWN_TAGS = new HashSet<String>(Arrays.asList(new String[] {
           "@apiNote",
           "@author",
-          "@since",
           "@version",
+          //not used by metalava for Android docs (see @apiSince)
+          "@since",
+          //value is an Android API level (set automatically by metalava)
+          "@apiSince",
           "@deprecated",
+          //value is an Android API level (set automatically by metalava)
+          "@deprecatedSince",
           "@undeprecate",
           "@docRoot",
           "@sdkCurrent",
@@ -45,8 +50,6 @@ public class Comment {
           "@implNote",
           "@implSpec",
           "@usesMathJax",
-          "@deprecatedSince",
-          "@apiSince",
       }));
 
   public Comment(String text, ContainerInfo base, SourcePositionInfo sp) {
@@ -287,8 +290,6 @@ public class Comment {
 
       for (char c = text.charAt(index);
               index < endOfBlock && !isWhitespaceChar(c); c = text.charAt(index++)) {}
-
-      //
       if (index == startOfBlock+1) {
           return;
       }
@@ -330,6 +331,10 @@ public class Comment {
       mInlineTagsList.add(new TextTagInfo("Text", "Text", text, pos));
     } else if (name.equals("@param")) {
       mParamTagsList.add(new ParamTagInfo("@param", "@param", text, mBase, pos));
+    } else if (name.equals("@apiSince")) {
+      setApiSince(text);
+    } else if (name.equals("@deprecatedSince")) {
+      setDeprecatedSince(text);
     } else if (name.equals("@see")) {
       mSeeTagsList.add(new SeeTagInfo("@see", "@see", text, mBase, pos));
     } else if (name.equals("@link")) {
@@ -526,6 +531,29 @@ public class Comment {
     return mRemoved;
   }
 
+  public void setDeprecatedSince(String since) {
+    if (since != null) {
+      since = since.trim();
+    }
+    mDeprecatedSince = since;
+  }
+
+  public String getDeprecatedSince() {
+    return mDeprecatedSince;
+  }
+
+  public void setApiSince(String since) {
+    if (since != null) {
+      since = since.trim();
+    }
+    mApiSince = since;
+  }
+
+  public String getApiSince() {
+    //return the value of @apiSince, an API level in Android
+    return mApiSince;
+  }
+
   public boolean isDocOnly() {
     if (mDocOnly == null) {
       mDocOnly = (mText != null) && (mText.indexOf("@doconly") >= 0);
@@ -601,6 +629,8 @@ public class Comment {
   Boolean mRemoved = null;
   Boolean mDocOnly = null;
   Boolean mDeprecated = null;
+  String mDeprecatedSince;
+  String mApiSince;
   String mText;
   ContainerInfo mBase;
   SourcePositionInfo mPosition;
diff --git a/src/com/google/doclava/DocInfo.java b/src/com/google/doclava/DocInfo.java
index 650ce0d..fae225f 100644
--- a/src/com/google/doclava/DocInfo.java
+++ b/src/com/google/doclava/DocInfo.java
@@ -101,6 +101,9 @@ public abstract class DocInfo {
   }
 
   public String getSince() {
+    if (Doclava.METALAVA_API_SINCE) {
+      mSince = comment().getApiSince();
+    }
     return mSince;
   }
 
@@ -129,11 +132,19 @@ public abstract class DocInfo {
   }
 
   public String getDeprecatedSince() {
-    return mDeprecatedSince;
+    if (Doclava.METALAVA_API_SINCE) {
+        return comment().getDeprecatedSince();
+    } else {
+        return mDeprecatedSince;
+    }
   }
 
   public boolean isDeprecated() {
-    return mDeprecatedSince != null ? true : false;
+    if (Doclava.METALAVA_API_SINCE) {
+      return comment().isDeprecated();
+    } else {
+      return mDeprecatedSince != null ? true : false;
+    }
   }
 
   public final void addFederatedReference(FederatedSite source) {
diff --git a/src/com/google/doclava/Doclava.java b/src/com/google/doclava/Doclava.java
index 564f104..f24718a 100644
--- a/src/com/google/doclava/Doclava.java
+++ b/src/com/google/doclava/Doclava.java
@@ -82,6 +82,7 @@ public class Doclava {
   public static boolean NAVTREE_ONLY = false;
   /* Generate reference navtree.js with all inherited members */
   public static boolean AT_LINKS_NAVTREE = false;
+  public static boolean METALAVA_API_SINCE = false;
   public static String outputPathBase = "/";
   public static ArrayList<String> inputPathHtmlDirs = new ArrayList<String>();
   public static ArrayList<String> inputPathHtmlDir2 = new ArrayList<String>();
@@ -331,6 +332,8 @@ public class Doclava {
         includeDefaultAssets = false;
       } else if (a[0].equals("-parsecomments")) {
         parseComments = true;
+      } else if (a[0].equals("-metalavaApiSince")) {
+        METALAVA_API_SINCE = true;
       } else if (a[0].equals("-since")) {
         sinceTagger.addVersion(a[1], a[2]);
       } else if (a[0].equals("-artifact")) {
@@ -528,6 +531,15 @@ public class Doclava {
           refPrefix = "gcm-";
         }
 
+        // Packages Pages
+        writePackages(refPrefix + "packages" + htmlExtension);
+
+        // Classes
+        writeClassLists();
+        writeClasses();
+        writeHierarchy();
+        // writeKeywords();
+
         // Write yaml tree.
         if (yamlNavFile != null) {
           if (yamlV2) {
@@ -542,15 +554,6 @@ public class Doclava {
           NavTree.writeNavTree(javadocDir, refPrefix);
         }
 
-        // Packages Pages
-        writePackages(refPrefix + "packages" + htmlExtension);
-
-        // Classes
-        writeClassLists();
-        writeClasses();
-        writeHierarchy();
-        // writeKeywords();
-
         // Lists for JavaScript
         writeLists();
         if (keepListFile != null) {
@@ -903,6 +906,9 @@ public class Doclava {
     if (option.equals("-parsecomments")) {
       return 1;
     }
+    if (option.equals("-metalavaApiSince")) {
+      return 1;
+    }
     if (option.equals("-since")) {
       return 3;
     }
@@ -1054,7 +1060,11 @@ public class Doclava {
           data.setValue("reference.gcm", "true");
       }
       data.setValue("reference", "1");
-      data.setValue("reference.apilevels", sinceTagger.hasVersions() ? "1" : "0");
+      if (METALAVA_API_SINCE) {
+        data.setValue("reference.apilevels", (pkg.getSince() != null) ? "1" : "0");
+      } else {
+        data.setValue("reference.apilevels", sinceTagger.hasVersions() ? "1" : "0");
+      }
       data.setValue("reference.artifacts", artifactTagger.hasArtifacts() ? "1" : "0");
       data.setValue("docs.packages." + i + ".name", s);
       data.setValue("docs.packages." + i + ".link", pkg.htmlPage());