Merge "Improve documentation for thread annotations."
diff --git a/annotations/src/main/java/androidx/annotation/AnyThread.java b/annotations/src/main/java/androidx/annotation/AnyThread.java
index e314445..c33fc3f 100644
--- a/annotations/src/main/java/androidx/annotation/AnyThread.java
+++ b/annotations/src/main/java/androidx/annotation/AnyThread.java
@@ -27,18 +27,51 @@
/**
* 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>
* @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>
+ * @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>
+ * @AnyThread
+ * public class Foo {
+ * @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 {
+ * @WorkerThread
+ * @MainThread
+ * void saveUser(User user) { ... }
+ *
+ * @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 2f944a9..92a426b 100644
--- a/annotations/src/main/java/androidx/annotation/BinderThread.java
+++ b/annotations/src/main/java/androidx/annotation/BinderThread.java
@@ -27,14 +27,47 @@
/**
* 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>
* @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>
+ * @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>
+ * @BinderThread
+ * public class Foo {
+ * @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 {
+ * @WorkerThread
+ * void saveUser(User user) { ... }
+ *
+ * @WorkerThread
+ * @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 fe54048..d1599d4 100644
--- a/annotations/src/main/java/androidx/annotation/MainThread.java
+++ b/annotations/src/main/java/androidx/annotation/MainThread.java
@@ -27,17 +27,51 @@
/**
* 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>
* @MainThread
- * public void deliverResult(D data) { ... }
+ * 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>
+ * @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>
+ * @MainThread
+ * public class Foo {
+ * @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 {
+ * @WorkerThread
+ * void saveUser(User user) { ... }
+ *
+ * @WorkerThread
+ * @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 f08290f..fdf6479 100644
--- a/annotations/src/main/java/androidx/annotation/UiThread.java
+++ b/annotations/src/main/java/androidx/annotation/UiThread.java
@@ -27,18 +27,50 @@
/**
* 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>
* @UiThread
+ * void setText(@NonNull String text) { ... }
+ * </code></pre>
*
- * public abstract void setText(@NonNull String text) { ... }
+ * <p>If the annotated element is a class, then all methods in the class should be called
+ * on the UI thread. </p>
+ *
+ * <pre><code>
+ * @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>
+ * @UiThread
+ * public class Foo {
+ * @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 {
+ * @WorkerThread
+ * void saveUser(User user) { ... }
+ *
+ * @WorkerThread
+ * @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 f102301..ac88dfb 100644
--- a/annotations/src/main/java/androidx/annotation/WorkerThread.java
+++ b/annotations/src/main/java/androidx/annotation/WorkerThread.java
@@ -27,13 +27,46 @@
/**
* 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>
* @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>
+ * @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>
+ * @WorkerThread
+ * public class Foo {
+ * @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 {
+ * @WorkerThread
+ * void saveUser(User user) { ... }
+ *
+ * @WorkerThread
+ * @UiThread
+ * boolean isEmpty(String value) { ... }
+ * }
* </code></pre>
*/
@Documented
