From 68b84b837fd60883ac8d06c6c4f03e3dfbb61c00 Mon Sep 17 00:00:00 2001 From: Dirk Dougherty Date: Sat, 16 Feb 2019 12:05:24 -0800 Subject: 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 --- res/assets/templates-sdk/page_info.cs | 7 ------ res/assets/templates/macros.cs | 15 +++++++++---- src/com/google/doclava/ClassInfo.java | 1 - src/com/google/doclava/Comment.java | 40 ++++++++++++++++++++++++++++++----- src/com/google/doclava/DocInfo.java | 15 +++++++++++-- src/com/google/doclava/Doclava.java | 30 +++++++++++++++++--------- 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)
-
Deprecated since version
Deprecated since - API level - - 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) ?> 0 ?> - added in -1 ?>versionAPI level - Android Developer PreviewAdded in Android +
Deprecated in version
Deprecated in + API level + + 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 KNOWN_TAGS = new HashSet(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 inputPathHtmlDirs = new ArrayList(); public static ArrayList inputPathHtmlDir2 = new ArrayList(); @@ -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()); -- cgit v1.2.3