From 6503bd8e33dbf6e8357256d43c6e1158e32a0268 Mon Sep 17 00:00:00 2001
From: Jeff Sharkey <jsharkey@android.com>
Date: Wed, 19 Apr 2017 23:24:18 -0600
Subject: Auto-generate docs based on annotations.

We have a handful of annotations that we've been sprinkling across
the platform APIs, such as @Nullable, @NonNull, @IntDef, etc.  It
would be really helpful to surface these contracts to developers
through the SDK docs.

This change allows annotations like those mentioned above to declare
the following new javadoc fields:

@memberDoc: docs to append to a field or method definition.
@paramDoc: docs to append to a @param definition.
@returnDoc: docs to append to a @return definition.

This change also builds a docstring to describe the list of all
constants listed in an @IntDef annotation.  Sadly AnnotationDesc
only passes along raw constant values, so we need the help of the
new "prefix" annotation argument to help find the field names.

Test: builds
Bug: 37526420
Change-Id: I4cfc00dd904e5dfa945b406d546e36846b7c0c28
---
 core/java/android/annotation/MainThread.java | 19 +++++++++++++------
 1 file changed, 13 insertions(+), 6 deletions(-)

(limited to 'core/java/android/annotation/MainThread.java')

diff --git a/core/java/android/annotation/MainThread.java b/core/java/android/annotation/MainThread.java
index 52f8dfb2dbb1..c6ac30c5c5da 100644
--- a/core/java/android/annotation/MainThread.java
+++ b/core/java/android/annotation/MainThread.java
@@ -23,20 +23,27 @@ import static java.lang.annotation.ElementType.METHOD;
 import static java.lang.annotation.ElementType.TYPE;
 import static java.lang.annotation.RetentionPolicy.SOURCE;
 
+import android.os.Looper;
+
 /**
  * Denotes that the annotated method should only be called on the main thread.
- * If the annotated element is a class, then all methods in the class should be called
- * on the main thread.
+ * If the annotated element is a class, then all methods in the class should be
+ * called on the main thread.
  * <p>
  * Example:
- * <pre><code>
+ *
+ * <pre>
+ * <code>
  *  &#64;MainThread
  *  public void deliverResult(D data) { ... }
- * </code></pre>
+ * </code>
+ * </pre>
  *
- * {@hide}
+ * @memberDoc This method must be called from the
+ *            {@linkplain Looper#getMainLooper() main thread} of your app.
+ * @hide
  */
 @Retention(SOURCE)
 @Target({METHOD,CONSTRUCTOR,TYPE})
 public @interface MainThread {
-}
\ No newline at end of file
+}
-- 
cgit v1.2.3