From ea58be972d43dbc21cc5381fd72e1f5df8727337 Mon Sep 17 00:00:00 2001
From: Daniel Yu <dsyu@google.com>
Date: Fri, 20 Nov 2015 14:08:34 -0800
Subject: [PATCH] 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
---
 docs/html/guide/components/bound-services.jd | 24 +++++++++++++-------
 1 file changed, 16 insertions(+), 8 deletions(-)

diff --git a/docs/html/guide/components/bound-services.jd b/docs/html/guide/components/bound-services.jd
index c2ac6074aaec3..f71ba8736be25 100644
--- a/docs/html/guide/components/bound-services.jd
+++ b/docs/html/guide/components/bound-services.jd
@@ -15,7 +15,11 @@ parent.link=services.html
       <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 @@ public class BindingActivity extends Activity {
 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 @@ onServiceConnected()} callback method, you can begin making calls to the service
 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 @@ and {@link android.content.Context#BIND_NOT_FOREGROUND}, or {@code 0} for none.<
 </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>