docs: Revised descriptions of binding and connecting to services.

Clarified that Context.bindService() returning true only indicates
that the system has found a service to bind to the client and that
ServiceConnection.onServiceConnected() might not be called if the
service encounters an error, such as crashing during startup.

Test: make ds-docs

Bug: 63118511
Change-Id: I0906de76abf4124d74f7f4f80ac0eab3cbf94f7e

diff --git a/core/java/android/content/Context.java b/core/java/android/content/Context.java
index c5c6aa2..56e4740 100644 (file)
--- a/core/java/android/content/Context.java
+++ b/core/java/android/content/Context.java
@@ -2851,10 +2851,12 @@ public abstract class Context {
      *          {@link #BIND_NOT_FOREGROUND}, {@link #BIND_ABOVE_CLIENT},
      *          {@link #BIND_ALLOW_OOM_MANAGEMENT}, or
      *          {@link #BIND_WAIVE_PRIORITY}.
-     * @return If you have successfully bound to the service, {@code true} is returned;
-     *         {@code false} is returned if the connection is not made so you will not
-     *         receive the service object. You should still call {@link #unbindService}
-     *         to release the connection even if this method returned {@code false}.
+     * @return {@code true} if the system is in the process of bringing up a
+     *         service that your client has permission to bind to; {@code false}
+     *         if the system couldn't find the service or if your client doesn't
+     *         have permission to bind to it. If this value is {@code true}, you
+     *         should later call {@link #unbindService} to release the
+     *         connection.
      *
      * @throws SecurityException If the caller does not have permission to access the service
      * or the service can not be found.

diff --git a/core/java/android/content/ServiceConnection.java b/core/java/android/content/ServiceConnection.java
index c16dbbe..21398f6 100644 (file)
--- a/core/java/android/content/ServiceConnection.java
+++ b/core/java/android/content/ServiceConnection.java
@@ -31,6 +31,11 @@ public interface ServiceConnection {
      * the {@link android.os.IBinder} of the communication channel to the
      * Service.
      *
+     * <p class="note"><b>Note:</b> If the system has started to bind your
+     * client app to a service, it's possible that your app will never receive
+     * this callback. Your app won't receive a callback if there's an issue with
+     * the service, such as the service crashing while being created.
+     *
      * @param name The concrete component name of the service that has
      * been connected.
      *