Clarify how Handler is used in IC#getHandler()

Since its beginning [1] the system has been using

  InputConnection#getHandler()

only for retrieving Looper associated with it.  Although it has been
intentional, it'd be probably helpful for app developers if we can
clarify a bit more on this, because most likely the current behavior
is not going to change.

This CL also annotates the API with @Nullable as it should have been.

 [1]: Id9e579bb3e2966986cdcb1c34bc8cacfeca2e1a9
      612cce92ad

Bug: 26945674
Fix: 195434171
Test: presubmit
Change-Id: I14910c6f0cc43feec505b2951625d0c00203ac92

core/api/current.txt

@@ -51933,7 +51933,7 @@ package android.view.inputmethod {
     method public boolean finishComposingText();
     method public int getCursorCapsMode(int);
     method public android.view.inputmethod.ExtractedText getExtractedText(android.view.inputmethod.ExtractedTextRequest, int);
-    method public android.os.Handler getHandler();
+    method @Nullable public android.os.Handler getHandler();
     method public CharSequence getSelectedText(int);
     method @Nullable public default android.view.inputmethod.SurroundingText getSurroundingText(@IntRange(from=0) int, @IntRange(from=0) int, int);
     method @Nullable public CharSequence getTextAfterCursor(@IntRange(from=0) int, int);

core/java/android/view/inputmethod/InputConnection.java

@@ -927,14 +927,20 @@ public interface InputConnection {
     boolean requestCursorUpdates(int cursorUpdateMode);
 
     /**
-     * Called by the {@link InputMethodManager} to enable application developers to specify a
-     * dedicated {@link Handler} on which incoming IPC method calls from input methods will be
-     * dispatched.
+     * Called by the system to enable application developers to specify a dedicated thread on which
+     * {@link InputConnection} methods are called back.
      *
-     * <p>Note: This does nothing when called from input methods.</p>
+     * <p><strong>Editor authors</strong>: although you can return your custom subclasses of
+     * {@link Handler}, the system only uses {@link android.os.Looper} returned from
+     * {@link Handler#getLooper()}.  You cannot intercept or cancel {@link InputConnection}
+     * callbacks by implementing this method.</p>
+     *
+     * <p><strong>IME authors</strong>: This method is not intended to be called from the IME.  You
+     * will always receive {@code null}.</p>
      *
      * @return {@code null} to use the default {@link Handler}.
      */
+    @Nullable
     Handler getHandler();
 
     /**