Expose some useful methods on Looper and clean up docs.

Change-Id: I40796c3ba07d3c50043da56e835f11fbf9852d30

1 files changed, 39 insertions, 25 deletions

diff --git a/core/java/android/os/Looper.java b/core/java/android/os/Looper.java
index 7384dd2..9b3880b 100644
--- a/core/java/android/os/Looper.java
+++ b/core/java/android/os/Looper.java
@@ -16,6 +16,8 @@
 
 package android.os;
 
+import android.annotation.NonNull;
+import android.annotation.Nullable;
 import android.util.Log;
 import android.util.Printer;
 
@@ -24,10 +26,10 @@ import android.util.Printer;
   * not have a message loop associated with them; to create one, call
   * {@link #prepare} in the thread that is to run the loop, and then
   * {@link #loop} to have it process messages until the loop is stopped.
-  * 
+  *
   * <p>Most interaction with a message loop is through the
   * {@link Handler} class.
-  * 
+  *
   * <p>This is a typical example of the implementation of a Looper thread,
   * using the separation of {@link #prepare} and {@link #loop} to create an
   * initial Handler to communicate with the Looper.
@@ -57,7 +59,7 @@ public final class Looper {
      * based on MessageQueue.  APIs that affect the state of the queue should be
      * defined on MessageQueue or Handler rather than on Looper itself.  For example,
      * idle handlers and sync barriers are defined on the queue whereas preparing the
-     * thread, looping and quitting are defined on the looper.
+     * thread, looping, and quitting are defined on the looper.
      */
 
     private static final String TAG = "Looper";
@@ -104,7 +106,8 @@ public final class Looper {
         }
     }
 
-    /** Returns the application's main looper, which lives in the main thread of the application.
+    /**
+     * Returns the application's main looper, which lives in the main thread of the application.
      */
     public static Looper getMainLooper() {
         synchronized (Looper.class) {
@@ -167,29 +170,16 @@ public final class Looper {
      * Return the Looper object associated with the current thread.  Returns
      * null if the calling thread is not associated with a Looper.
      */
-    public static Looper myLooper() {
+    public static @Nullable Looper myLooper() {
         return sThreadLocal.get();
     }
 
     /**
-     * Control logging of messages as they are processed by this Looper.  If
-     * enabled, a log message will be written to <var>printer</var> 
-     * at the beginning and ending of each message dispatch, identifying the
-     * target Handler and message contents.
-     * 
-     * @param printer A Printer object that will receive log messages, or
-     * null to disable message logging.
-     */
-    public void setMessageLogging(Printer printer) {
-        mLogging = printer;
-    }
-    
-    /**
      * Return the {@link MessageQueue} object associated with the current
      * thread.  This must be called from a thread running a Looper, or a
      * NullPointerException will be thrown.
      */
-    public static MessageQueue myQueue() {
+    public static @NonNull MessageQueue myQueue() {
         return myLooper().mQueue;
     }
 
@@ -200,13 +190,25 @@ public final class Looper {
 
     /**
      * Returns true if the current thread is this looper's thread.
-     * @hide
      */
     public boolean isCurrentThread() {
         return Thread.currentThread() == mThread;
     }
 
     /**
+     * Control logging of messages as they are processed by this Looper.  If
+     * enabled, a log message will be written to <var>printer</var>
+     * at the beginning and ending of each message dispatch, identifying the
+     * target Handler and message contents.
+     *
+     * @param printer A Printer object that will receive log messages, or
+     * null to disable message logging.
+     */
+    public void setMessageLogging(@Nullable Printer printer) {
+        mLogging = printer;
+    }
+
+    /**
      * Quits the looper.
      * <p>
      * Causes the {@link #loop} method to terminate without processing any
@@ -243,18 +245,30 @@ public final class Looper {
     }
 
     /**
-     * Return the Thread associated with this Looper.
+     * Gets the Thread associated with this Looper.
+     *
+     * @return The looper's thread.
      */
-    public Thread getThread() {
+    public @NonNull Thread getThread() {
         return mThread;
     }
 
-    /** @hide */
-    public MessageQueue getQueue() {
+    /**
+     * Gets this looper's message queue.
+     *
+     * @return The looper's message queue.
+     */
+    public @NonNull MessageQueue getQueue() {
         return mQueue;
     }
 
-    public void dump(Printer pw, String prefix) {
+    /**
+     * Dumps the state of the looper for debugging purposes.
+     *
+     * @param pw A printer to receive the contents of the dump.
+     * @param prefix A prefix to prepend to each line which is printed.
+     */
+    public void dump(@NonNull Printer pw, @NonNull String prefix) {
         pw.println(prefix + toString());
         mQueue.dump(pw, prefix + "  ");
     }