diff options
author | Dirk Dougherty <ddougherty@google.com> | 2019-02-25 22:40:06 +0000 |
---|---|---|
committer | Android (Google) Code Review <android-gerrit@google.com> | 2019-02-25 22:40:06 +0000 |
commit | eb75011a62b68ae2e74587f352df3efe4ee230be (patch) | |
tree | 693bdb0bd8b568a1815a0b5d44b67e120410ad96 | |
parent | cd59a4a0aa8b7c84ab9b154a049bb3a1b6468d84 (diff) | |
parent | 68b84b837fd60883ac8d06c6c4f03e3dfbb61c00 (diff) | |
download | platform_external_doclava-eb75011a62b68ae2e74587f352df3efe4ee230be.tar.gz platform_external_doclava-eb75011a62b68ae2e74587f352df3efe4ee230be.tar.bz2 platform_external_doclava-eb75011a62b68ae2e74587f352df3efe4ee230be.zip |
Merge "Update doclava to use @since tags from comments."
-rw-r--r-- | res/assets/templates-sdk/page_info.cs | 7 | ||||
-rw-r--r-- | res/assets/templates/macros.cs | 15 | ||||
-rw-r--r-- | src/com/google/doclava/ClassInfo.java | 1 | ||||
-rw-r--r-- | src/com/google/doclava/Comment.java | 40 | ||||
-rw-r--r-- | src/com/google/doclava/DocInfo.java | 15 | ||||
-rw-r--r-- | 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) <?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()); |