cherrypick Change-Id: I1365c6c45f8e1f75ee4afbc52c32778d21b97be4 from master

docs: Rewrite of App Fundamentals.. Part 2.
This introduces three new docs:

Services:
  Provides an introduction to using services and describes the
  service lifecycle (previously in the "Component Lifecycles" section
  of the fundamentals.jd document)
Bound Services:
  A guide for services that offer binding.
AIDL:
  A doc about using AIDL (primarily for creating a service interface)

Also includes edits to IntentService javadocs to clarify
different behaviors for some callback methods

Includes a new version of the services lifecycle diagram
and an additional diagram for determining onRebind()

These files are orphaned for now---they're not linked in the sidenav,
until I get the last couple documents submitted for the app fundamentals.

Change-Id: I7fb0a8faff1f18b7d6b9a7b59f66f55a1b6168f1

1 files changed, 13 insertions, 0 deletions

diff --git a/core/java/android/app/IntentService.java b/core/java/android/app/IntentService.java
index 7c2d3a0..57a2695 100644
--- a/core/java/android/app/IntentService.java
+++ b/core/java/android/app/IntentService.java
@@ -113,6 +113,12 @@ public abstract class IntentService extends Service {
         mServiceHandler.sendMessage(msg);
     }
 
+    /**
+     * You should not override this method for your IntentService. Instead,
+     * override {@link #onHandleIntent}, which the system calls when the IntentService
+     * receives a start request.
+     * @see android.app.Service#onStartCommand
+     */
     @Override
     public int onStartCommand(Intent intent, int flags, int startId) {
         onStart(intent, startId);
@@ -124,6 +130,11 @@ public abstract class IntentService extends Service {
         mServiceLooper.quit();
     }
 
+    /**
+     * Unless you provide binding for your service, you don't need to implement this
+     * method, because the default implementation returns null. 
+     * @see android.app.Service#onBind
+     */
     @Override
     public IBinder onBind(Intent intent) {
         return null;
@@ -135,6 +146,8 @@ public abstract class IntentService extends Service {
      * worker thread that runs independently from other application logic.
      * So, if this code takes a long time, it will hold up other requests to
      * the same IntentService, but it will not hold up anything else.
+     * When all requests have been handled, the IntentService stops itself,
+     * so you should not call {@link #stopSelf}.
      *
      * @param intent The value passed to {@link
      *               android.content.Context#startService(Intent)}.