Merge "Improve documentation for thread annotations." am: d39248f05d

am: 6632e99d3d

Change-Id: Ia9ea17079e19660c14101945f56bb8ee4fadc783

5 files changed, 191 insertions, 26 deletions

diff --git a/annotations/src/main/java/androidx/annotation/AnyThread.java b/annotations/src/main/java/androidx/annotation/AnyThread.java
index e3144454c90..c33fc3fed34 100644
--- a/annotations/src/main/java/androidx/annotation/AnyThread.java
+++ b/annotations/src/main/java/androidx/annotation/AnyThread.java
@@ -27,18 +27,51 @@ import java.lang.annotation.Target;
 
 /**
  * Denotes that the annotated method can be called from any thread (e.g. it is "thread safe".)
- * If the annotated element is a class, then all methods in the class can be called
- * from any thread.
  * <p>
- * The main purpose of this method is to indicate that you believe a method can be called
+ * The main purpose of this annotation is to indicate that you believe a method can be called
  * from any thread; static tools can then check that nothing you call from within this method
  * or class have more strict threading requirements.
- * <p>
- * Example:
  * <pre><code>
  *  &#64;AnyThread
  *  public void deliverResult(D data) { ... }
  * </code></pre>
+ *
+ * <p>If the annotated element is a class, then all methods in the class can be called
+ * from any thread. </p>
+ *
+ * <pre><code>
+ *  &#64;AnyThread
+ *  public class Foo { ... }
+ * </code></pre>
+ *
+ * <p>When the class is annotated, but one of the methods has another threading annotation such as
+ * {@link MainThread}, the method annotation takes precedence. In the following example,
+ * <code>onResult()</code> should only be called on the main thread.</p>
+ *
+ * <pre><code>
+ *  &#64;AnyThread
+ *  public class Foo {
+ *      &#64;MainThread
+ *      void onResult(String result) { ... }
+ *  }
+ * </code></pre>
+ *
+ * <p>Multiple threading annotations can be combined. Following example illustrates that,
+ * <code>saveUser()</code> can be called on a worker thread or the main thread.
+ * It's safe for <code>saveUser()</code> to invoke <code>isEmpty()</code>, whereas it's not safe
+ * for <code>isEmpty()</code> to invoke <code>saveUser()</code>.
+ * </p>
+ *
+ * <pre><code>
+ *  public class Foo {
+ *      &#64;WorkerThread
+ *      &#64;MainThread
+ *      void saveUser(User user) { ... }
+ *
+ *      &#64;AnyThread
+ *      boolean isEmpty(String value) { ... }
+ *  }
+ * </code></pre>
  */
 @Documented
 @Retention(CLASS)
diff --git a/annotations/src/main/java/androidx/annotation/BinderThread.java b/annotations/src/main/java/androidx/annotation/BinderThread.java
index 2f944a9df45..92a426b2239 100644
--- a/annotations/src/main/java/androidx/annotation/BinderThread.java
+++ b/annotations/src/main/java/androidx/annotation/BinderThread.java
@@ -27,14 +27,47 @@ import java.lang.annotation.Target;
 
 /**
  * Denotes that the annotated method should only be called on the binder thread.
- * If the annotated element is a class, then all methods in the class should be called
- * on the binder thread.
- * <p>
- * Example:
  * <pre><code>
  *  &#64;BinderThread
  *  public BeamShareData createBeamShareData() { ... }
  * </code></pre>
+ *
+ * <p>If the annotated element is a class, then all methods in the class should be called
+ * on the binder thread. </p>
+ *
+ * <pre><code>
+ *  &#64;BinderThread
+ *  public class Foo { ... }
+ * </code></pre>
+ *
+ * <p>When the class is annotated, but one of the methods has another threading annotation such as
+ * {@link UiThread}, the method annotation takes precedence. In the following example,
+ * <code>setText()</code> should be called on the UI thread.</p>
+ *
+ * <pre><code>
+ *  &#64;BinderThread
+ *  public class Foo {
+ *      &#64;UiThread
+ *      void setText(String text) { ... }
+ *  }
+ * </code></pre>
+ *
+ * <p>Multiple threading annotations can be combined. Following example illustrates that,
+ * <code>isEmpty()</code> can be called on a worker thread or the binder thread.
+ * It's safe for <code>saveUser()</code> to invoke <code>isEmpty()</code>, whereas it's not safe
+ * for <code>isEmpty()</code> to invoke <code>saveUser()</code>.
+ * </p>
+ *
+ * <pre><code>
+ *  public class Foo {
+ *      &#64;WorkerThread
+ *      void saveUser(User user) { ... }
+ *
+ *      &#64;WorkerThread
+ *      &#64;BinderThread
+ *      boolean isEmpty(String value) { ... }
+ *  }
+ * </code></pre>
  */
 @Documented
 @Retention(CLASS)
diff --git a/annotations/src/main/java/androidx/annotation/MainThread.java b/annotations/src/main/java/androidx/annotation/MainThread.java
index fe5404803d4..d1599d4c765 100644
--- a/annotations/src/main/java/androidx/annotation/MainThread.java
+++ b/annotations/src/main/java/androidx/annotation/MainThread.java
@@ -27,17 +27,51 @@ import java.lang.annotation.Target;
 
 /**
  * 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.
- * <p>
- * Example:
+ *
+ * <pre><code>
+ *  &#64;MainThread
+ *  void deliverResult(D data) { ... }
+ * </code></pre>
+ *
+ * <p>If the annotated element is a class, then all methods in the class should be called
+ * on the main thread. </p>
+ *
+ * <pre><code>
+ *  &#64;MainThread
+ *  public class Foo { ... }
+ * </code></pre>
+ *
+ * <p>When the class is annotated, but one of the methods has another threading annotation such as
+ * {@link WorkerThread}, the method annotation takes precedence. In the following example,
+ * <code>getUser()</code> should be called on a worker thread.</p>
+ *
  * <pre><code>
  *  &#64;MainThread
- *  public void deliverResult(D data) { ... }
+ *  public class Foo {
+ *      &#64;WorkerThread
+ *      User getUser() { ... }
+ *  }
+ * </code></pre>
+ *
+ * <p>Multiple threading annotations can be combined. Following example illustrates that,
+ * <code>isEmpty()</code> can be called on a worker thread or the main thread.
+ * It's safe for <code>saveUser()</code> to invoke <code>isEmpty()</code>, whereas it's not safe
+ * for <code>isEmpty()</code> to invoke <code>saveUser()</code>.
+ * </p>
+ *
+ * <pre><code>
+ *  public class Foo {
+ *      &#64;WorkerThread
+ *      void saveUser(User user) { ... }
+ *
+ *      &#64;WorkerThread
+ *      &#64;MainThread
+ *      boolean isEmpty(String value) { ... }
+ *  }
  * </code></pre>
  *
  * <p class="note"><b>Note:</b> Ordinarily, an app's main thread is also the UI
- * thread. However, However, under special circumstances, an app's main thread
+ * thread. However, under special circumstances, an app's main thread
  * might not be its UI thread; for more information, see
  * <a href="/studio/write/annotations.html#thread-annotations">Thread
  * annotations</a>.
diff --git a/annotations/src/main/java/androidx/annotation/UiThread.java b/annotations/src/main/java/androidx/annotation/UiThread.java
index f08290f3962..fdf647924c2 100644
--- a/annotations/src/main/java/androidx/annotation/UiThread.java
+++ b/annotations/src/main/java/androidx/annotation/UiThread.java
@@ -27,18 +27,50 @@ import java.lang.annotation.Target;
 
 /**
  * Denotes that the annotated method or constructor should only be called on the UI thread.
- * If the annotated element is a class, then all methods in the class should be called
- * on the UI thread.
- * <p>
- * Example:
  * <pre><code>
  *  &#64;UiThread
+ *  void setText(@NonNull String text) { ... }
+ * </code></pre>
+ *
+ * <p>If the annotated element is a class, then all methods in the class should be called
+ * on the UI thread. </p>
+ *
+ * <pre><code>
+ *  &#64;UiThread
+ *  public class Foo { ... }
+ * </code></pre>
+ *
+ * <p>When the class is annotated, but one of the methods has another threading annotation such as
+ * {@link WorkerThread}, the method annotation takes precedence. In the following example,
+ * <code>getUser()</code> should be called on a worker thread.</p>
+ *
+ * <pre><code>
+ *  &#64;UiThread
+ *  public class Foo {
+ *      &#64;WorkerThread
+ *      User getUser() { ... }
+ *  }
+ * </code></pre>
+ *
+ * <p>Multiple threading annotations can be combined. Following example illustrates that,
+ * <code>isEmpty()</code> can be called on a worker thread or the main thread.
+ * It's safe for <code>saveUser()</code> to invoke <code>isEmpty()</code>, whereas it's not safe
+ * for <code>isEmpty()</code> to invoke <code>saveUser()</code>.
+ * </p>
+ *
+ * <pre><code>
+ *  public class Foo {
+ *      &#64;WorkerThread
+ *      void saveUser(User user) { ... }
  *
- *  public abstract void setText(@NonNull String text) { ... }
+ *      &#64;WorkerThread
+ *      &#64;UiThread
+ *      boolean isEmpty(String value) { ... }
+ *  }
  * </code></pre>
  *
  * <p class="note"><b>Note:</b> Ordinarily, an app's UI thread is also the main
- * thread. However, However, under special circumstances, an app's UI thread
+ * thread. However, under special circumstances, an app's UI thread
  * might not be its main thread; for more information, see
  * <a href="/studio/write/annotations.html#thread-annotations">Thread
  * annotations</a>.
diff --git a/annotations/src/main/java/androidx/annotation/WorkerThread.java b/annotations/src/main/java/androidx/annotation/WorkerThread.java
index f1023018b45..ac88dfb7622 100644
--- a/annotations/src/main/java/androidx/annotation/WorkerThread.java
+++ b/annotations/src/main/java/androidx/annotation/WorkerThread.java
@@ -27,13 +27,46 @@ import java.lang.annotation.Target;
 
 /**
  * Denotes that the annotated method should only be called on a worker thread.
- * If the annotated element is a class, then all methods in the class should be called
- * on a worker thread.
- * <p>
- * Example:
  * <pre><code>
  *  &#64;WorkerThread
- *  protected abstract FilterResults performFiltering(CharSequence constraint);
+ *  FilterResults performFiltering(CharSequence constraint);
+ * </code></pre>
+ *
+ * <p>If the annotated element is a class, then all methods in the class should be called
+ * on a worker thread. </p>
+ *
+ * <pre><code>
+ *  &#64;WorkerThread
+ *  public class Foo { ... }
+ * </code></pre>
+ *
+ * <p>When the class is annotated, but one of the methods has another threading annotation such as
+ * {@link MainThread}, the method annotation takes precedence. In the following example,
+ * <code>onResult()</code> should be called on the main thread.</p>
+ *
+ * <pre><code>
+ *  &#64;WorkerThread
+ *  public class Foo {
+ *      &#64;MainThread
+ *      void onResult(String result) { ... }
+ *  }
+ * </code></pre>
+ *
+ * <p>Multiple threading annotations can be combined. Following example illustrates that,
+ * <code>isEmpty()</code> can be called on the worker thread or the main thread.
+ * It's safe for <code>saveUser()</code> to invoke <code>isEmpty()</code>, whereas it's not safe
+ * for <code>isEmpty()</code> to invoke <code>saveUser()</code>.
+ * </p>
+ *
+ * <pre><code>
+ *  public class Foo {
+ *      &#64;WorkerThread
+ *      void saveUser(User user) { ... }
+ *
+ *      &#64;WorkerThread
+ *      &#64;UiThread
+ *      boolean isEmpty(String value) { ... }
+ *  }
  * </code></pre>
  */
 @Documented