docs: Fixing details on when clients unbind from Bound Service
Docs were slightly contradictory on when clients should unbind.
Changed a few sections to point to one "source of truth" section
that explains the appropriate times to call unbindService().
Updated with corrections to issues found by Andrew and Dave.
Bug: 8135078
Change-Id: If8afb998cbd2efceef075ee6633cf0744c50d1df
diff --git a/docs/html/guide/components/bound-services.jd b/docs/html/guide/components/bound-services.jd
index c2ac607..f71ba87 100644
--- a/docs/html/guide/components/bound-services.jd
+++ b/docs/html/guide/components/bound-services.jd
@@ -15,7 +15,11 @@
<li><a href="#Messenger">Using a Messenger</a></li>
</ol>
</li>
- <li><a href="#Binding">Binding to a Service</a></li>
+ <li><a href="#Binding">Binding to a Service</a>
+ <ol>
+ <li><a href="#Additional_Notes">Additional notes</a></li>
+ </ol>
+ </li>
<li><a href="#Lifecycle">Managing the Lifecycle of a Bound Service</a></li>
</ol>
@@ -309,8 +313,11 @@
android.content.ServiceConnection#onServiceConnected onServiceConnected()} callback. The next
section provides more information about this process of binding to the service.</p>
-<p class="note"><strong>Note:</strong> The example above doesn't explicitly unbind from the service,
-but all clients should unbind at an appropriate time (such as when the activity pauses).</p>
+<p class="note"><strong>Note:</strong> In the example above, the
+{@link android.app.Activity#onStop onStop()} method unbinds the client from the service. Clients
+should unbind from services at appropriate times, as discussed in
+<a href="#Additional_Notes">Additional Notes</a>.
+</p>
<p>For more sample code, see the <a
href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/app/LocalService.html">{@code
@@ -538,10 +545,11 @@
the methods defined by the interface.</li>
<li>To disconnect from the service, call {@link
android.content.Context#unbindService unbindService()}.
- <p>When your client is destroyed, it will unbind from the service, but you should always unbind
-when you're done interacting with the service or when your activity pauses so that the service can
-shutdown while its not being used. (Appropriate times to bind and unbind is discussed
-more below.)</p>
+ <p>If your client is still bound to a service when your app destroys the client, destruction
+causes the client to unbind. It is better practice to unbind the client as soon as it is done
+interacting with the service. Doing so allows the idle service to shut down. For more information
+about appropriate times to bind and unbind, see <a href="#Additional_Notes">Additional Notes</a>.
+</p>
</li>
</ol>
@@ -591,7 +599,7 @@
</ul>
-<h3>Additional notes</h3>
+<h3 id="Additional_Notes">Additional notes</h3>
<p>Here are some important notes about binding to a service:</p>
<ul>