Add RequiresFeature annotation.

Certain APIs require that a device have a specific feature to operate
correctly, so start annotating them.

Test: manual inspection of docs
Bug: 72284763
Change-Id: I0ee5ce4868cae5e1f05f614f2241a168f1170be5

2 files changed, 56 insertions, 6 deletions

diff --git a/res/assets/templates-sdk/macros_override.cs b/res/assets/templates-sdk/macros_override.cs
index 08ed856..b475798 100644
--- a/res/assets/templates-sdk/macros_override.cs
+++ b/res/assets/templates-sdk/macros_override.cs
@@ -67,6 +67,7 @@ def:aux_tag_list(tags) ?><?cs
       elif:tag.kind == "@stringDef" ?><?cs call:dump_string_def(tag) ?><?cs
       elif:tag.kind == "@permission" ?><?cs call:dump_permission(tag) ?><?cs
       elif:tag.kind == "@service" ?><?cs call:dump_service(tag) ?><?cs
+      elif:tag.kind == "@feature" ?><?cs call:dump_feature(tag) ?><?cs
       /if ?><?cs
   /each ?></p><?cs
 /def ?><?cs
@@ -135,4 +136,10 @@ def:dump_service(tag) ?>Instances of this class must be obtained using <?cs
     if i < subcount(tag.values) - 2 ?> or <?cs
     /if ?><?cs
   /loop ?>.<?cs
+/def ?><?cs
+
+# Print output for @feature tags ?><?cs
+def:dump_feature(tag) ?>Requires the <?cs
+  call:tag_list(tag.values[0].commentTags) ?> feature which can be detected using <?cs
+  call:tag_list(tag.values[1].commentTags) ?>.<?cs
 /def ?>
diff --git a/src/com/google/doclava/AndroidAuxSource.java b/src/com/google/doclava/AndroidAuxSource.java
index b5735e3..cfcc0ac 100644
--- a/src/com/google/doclava/AndroidAuxSource.java
+++ b/src/com/google/doclava/AndroidAuxSource.java
@@ -23,10 +23,11 @@ import java.util.Map;
 import java.util.regex.Pattern;
 
 public class AndroidAuxSource implements AuxSource {
-  private static final int TYPE_FIELD = 0;
-  private static final int TYPE_METHOD = 1;
-  private static final int TYPE_PARAM = 2;
-  private static final int TYPE_RETURN = 3;
+  private static final int TYPE_CLASS = 0;
+  private static final int TYPE_FIELD = 1;
+  private static final int TYPE_METHOD = 2;
+  private static final int TYPE_PARAM = 3;
+  private static final int TYPE_RETURN = 4;
 
   @Override
   public TagInfo[] classAuxTags(ClassInfo clazz) {
@@ -72,6 +73,7 @@ public class AndroidAuxSource implements AuxSource {
             valueTags.toArray(TagInfo.getArray(valueTags.size()))));
       }
     }
+    auxTags(TYPE_CLASS, clazz.annotations(), toString(clazz.inlineTags()), tags);
     return tags.toArray(TagInfo.getArray(tags.size()));
   }
 
@@ -103,6 +105,12 @@ public class AndroidAuxSource implements AuxSource {
   private static TagInfo[] auxTags(int type, List<AnnotationInstanceInfo> annotations,
       String[] comment) {
     ArrayList<TagInfo> tags = new ArrayList<>();
+    auxTags(type, annotations, comment, tags);
+    return tags.toArray(TagInfo.getArray(tags.size()));
+  }
+
+  private static void auxTags(int type, List<AnnotationInstanceInfo> annotations,
+      String[] comment, ArrayList<TagInfo> tags) {
     for (AnnotationInstanceInfo annotation : annotations) {
       // Ignore null-related annotations when docs already mention
       if (annotation.type().qualifiedNameMatches("android", "annotation.NonNull")
@@ -121,6 +129,7 @@ public class AndroidAuxSource implements AuxSource {
       switch (type) {
         case TYPE_METHOD:
         case TYPE_FIELD:
+        case TYPE_CLASS:
           docTags = annotation.type().comment().memberDocTags();
           break;
         case TYPE_PARAM:
@@ -135,7 +144,7 @@ public class AndroidAuxSource implements AuxSource {
       }
 
       // Document required permissions
-      if ((type == TYPE_METHOD || type == TYPE_FIELD)
+      if ((type == TYPE_CLASS || type == TYPE_METHOD || type == TYPE_FIELD)
           && annotation.type().qualifiedNameMatches("android", "annotation.RequiresPermission")) {
         ArrayList<AnnotationValueInfo> values = null;
         boolean any = false;
@@ -176,6 +185,41 @@ public class AndroidAuxSource implements AuxSource {
             valueTags.toArray(TagInfo.getArray(valueTags.size()))));
       }
 
+      // Document required features
+      if ((type == TYPE_CLASS || type == TYPE_METHOD || type == TYPE_FIELD)
+          && annotation.type().qualifiedNameMatches("android", "annotation.RequiresFeature")) {
+        AnnotationValueInfo value = null;
+        for (AnnotationValueInfo val : annotation.elementValues()) {
+          switch (val.element().name()) {
+            case "value":
+              value = val;
+              break;
+          }
+        }
+        if (value == null) continue;
+
+        ClassInfo pmClass = annotation.type().findClass("android.content.pm.PackageManager");
+        ArrayList<TagInfo> valueTags = new ArrayList<>();
+        final String expected = String.valueOf(value.value());
+        for (FieldInfo field : pmClass.fields()) {
+          if (field.isHiddenOrRemoved()) continue;
+          if (String.valueOf(field.constantValue()).equals(expected)) {
+            valueTags.add(new ParsedTagInfo("", "",
+                "{@link " + pmClass.qualifiedName() + "#" + field.name() + "}", null,
+                SourcePositionInfo.UNKNOWN));
+          }
+        }
+
+        valueTags.add(new ParsedTagInfo("", "",
+            "{@link android.content.pm.PackageManager#hasSystemFeature(String)"
+                + " PackageManager.hasSystemFeature(String)}",
+            null, SourcePositionInfo.UNKNOWN));
+
+        Map<String, String> args = new HashMap<>();
+        tags.add(new AuxTagInfo("@feature", "@feature", SourcePositionInfo.UNKNOWN, args,
+            valueTags.toArray(TagInfo.getArray(valueTags.size()))));
+      }
+
       // The remaining annotations below always appear on return docs, and
       // should not be included in the method body
       if (type == TYPE_METHOD) continue;
@@ -261,7 +305,6 @@ public class AndroidAuxSource implements AuxSource {
         }
       }
     }
-    return tags.toArray(TagInfo.getArray(tags.size()));
   }
 
   private static String[] toString(TagInfo[] tags) {