Automatic documentation for "@Column" annotation.

We have various "contract" classes across the OS which describe the
columns that are available for insert(), update(), and query() when
working with ContentProviders.

To help ensure that the underlying providers fully support the API
contracts being made, this change defines a new "@Column" annotation
which describes the underlying data type.

These annotations can then be used by the ContentProvider
implementations internally to ensure that they're fully meeting the
API contracts being made.

Bug: 120429729
Test: manual
Change-Id: Iffeb5fce4a1186e0b4aa3424ecb69a34f6607c21

2 files changed, 52 insertions, 0 deletions

diff --git a/res/assets/templates-sdk/macros_override.cs b/res/assets/templates-sdk/macros_override.cs
index 8ef81cf..5c0c482 100644
--- a/res/assets/templates-sdk/macros_override.cs
+++ b/res/assets/templates-sdk/macros_override.cs
@@ -68,6 +68,7 @@ def:aux_tag_list(tags) ?><?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
+      elif:tag.kind == "@column" ?><?cs call:dump_column(tag) ?><?cs
       /if ?><?cs
   /each ?></p><?cs
 /def ?><?cs
@@ -143,3 +144,14 @@ 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 ?>
+
+# Print output for @column tags ?><?cs
+def:dump_column(tag) ?>This constant represents a column name that can be used with a <?cs
+  call:tag_list(tag.values[0].commentTags) ?> through a <?cs
+  call:tag_list(tag.values[1].commentTags) ?> or <?cs
+  call:tag_list(tag.values[2].commentTags) ?> object. The values stored in this column are <?cs
+  call:tag_list(tag.values[3].commentTags) ?><?cs
+  if tag.readOnly ?>, and are read-only and cannot be mutated<?cs
+  else ?><?cs
+  /if ?>.<?cs
+/def ?>
diff --git a/src/com/google/doclava/AndroidAuxSource.java b/src/com/google/doclava/AndroidAuxSource.java
index 1c97b18..ca1fbd0 100644
--- a/src/com/google/doclava/AndroidAuxSource.java
+++ b/src/com/google/doclava/AndroidAuxSource.java
@@ -219,6 +219,46 @@ public class AndroidAuxSource implements AuxSource {
             valueTags.toArray(TagInfo.getArray(valueTags.size()))));
       }
 
+      // Document provider columns
+      if ((type == TYPE_FIELD) && annotation.type().qualifiedNameMatches("android", "Column")) {
+        String value = null;
+        boolean readOnly = false;
+        for (AnnotationValueInfo val : annotation.elementValues()) {
+          switch (val.element().name()) {
+            case "value":
+              value = String.valueOf(val.value());
+              break;
+            case "readOnly":
+              readOnly = Boolean.parseBoolean(String.valueOf(val.value()));
+              break;
+          }
+        }
+
+        ArrayList<TagInfo> valueTags = new ArrayList<>();
+        valueTags.add(new ParsedTagInfo("", "",
+            "{@link android.content.ContentProvider}", null, SourcePositionInfo.UNKNOWN));
+        valueTags.add(new ParsedTagInfo("", "",
+            "{@link android.content.ContentValues}", null, SourcePositionInfo.UNKNOWN));
+        valueTags.add(new ParsedTagInfo("", "",
+            "{@link android.database.Cursor}", null, SourcePositionInfo.UNKNOWN));
+
+        ClassInfo cursorClass = annotation.type().findClass("android.database.Cursor");
+        for (FieldInfo field : cursorClass.fields()) {
+          if (field.isHiddenOrRemoved()) continue;
+          if (String.valueOf(field.constantValue()).equals(value)) {
+            valueTags.add(new ParsedTagInfo("", "",
+                "{@link android.database.Cursor#" + field.name() + "}",
+                null, SourcePositionInfo.UNKNOWN));
+          }
+        }
+        if (valueTags.size() < 4) continue;
+
+        Map<String, String> args = new HashMap<>();
+        if (readOnly) args.put("readOnly", "true");
+        tags.add(new AuxTagInfo("@column", "@column", 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;