From 37d1814ed7a15257f6ea206049597a2c494e4ef1 Mon Sep 17 00:00:00 2001
From: Kevin Hufnagle <khufnagle@google.com>
Date: Mon, 18 Apr 2016 16:11:21 -0700
Subject: [PATCH] docs: Clarified purpose of application "name" attr within
 manifest.

Improved descriptions of the "name" attribute of the <application>
element, which appears within an Android app's <manifest> element in
its manifest file. Also clarified connection between this attribute
and custom subclasses of the Application class.

Bug: 1232595
Change-Id: I79b6bd31224c7669b5dc509914a01ead84a049dc
Abandoned-Change-Id: Icee66f6b8df55c7fad414b4c19939a483dc7a165
---
 core/java/android/app/Application.java | 26 ++++++++++++++------------
 core/res/res/values/attrs_manifest.xml | 14 +++++++-------
 2 files changed, 21 insertions(+), 19 deletions(-)

diff --git a/core/java/android/app/Application.java b/core/java/android/app/Application.java
index 53f3b845a0884..156df36a600c0 100644
--- a/core/java/android/app/Application.java
+++ b/core/java/android/app/Application.java
@@ -28,19 +28,21 @@ import android.content.res.Configuration;
 import android.os.Bundle;
 
 /**
- * Base class for those who need to maintain global application state. You can
- * provide your own implementation by specifying its name in your
- * AndroidManifest.xml's &lt;application&gt; tag, which will cause that class
- * to be instantiated for you when the process for your application/package is
- * created.
+ * Base class for maintaining global application state. You can provide your own
+ * implementation by creating a subclass and specifying the fully-qualified name
+ * of this subclass as the <code>"android:name"</code> attribute in your
+ * AndroidManifest.xml's <code>&lt;application&gt;</code> tag. The Application
+ * class, or your subclass of the Application class, is instantiated before any
+ * other class when the process for your application/package is created.
  *
- * <p class="note">There is normally no need to subclass Application.  In
- * most situation, static singletons can provide the same functionality in a
- * more modular way.  If your singleton needs a global context (for example
- * to register broadcast receivers), the function to retrieve it can be
- * given a {@link android.content.Context} which internally uses
+ * <p class="note"><strong>Note: </strong>There is normally no need to subclass
+ * Application.  In most situations, static singletons can provide the same
+ * functionality in a more modular way.  If your singleton needs a global
+ * context (for example to register broadcast receivers), include
  * {@link android.content.Context#getApplicationContext() Context.getApplicationContext()}
- * when first constructing the singleton.</p>
+ * as a {@link android.content.Context} argument when invoking your singleton's
+ * <code>getInstance()</code> method.
+ * </p>
  */
 public class Application extends ContextWrapper implements ComponentCallbacks2 {
     private ArrayList<ComponentCallbacks> mComponentCallbacks =
@@ -287,4 +289,4 @@ public class Application extends ContextWrapper implements ComponentCallbacks2 {
             }
         }
     }
-}
+}
\ No newline at end of file
diff --git a/core/res/res/values/attrs_manifest.xml b/core/res/res/values/attrs_manifest.xml
index 0abcaa4df9581..c833e221277d2 100644
--- a/core/res/res/values/attrs_manifest.xml
+++ b/core/res/res/values/attrs_manifest.xml
@@ -1176,14 +1176,14 @@
          {@link #AndroidManifestActivity activity},
          {@link #AndroidManifestActivityAlias activity-alias}, and
          {@link #AndroidManifestUsesLibrary uses-library}.  The application tag
-         appears as a child of the root {@link #AndroidManifest manifest} tag. -->
+         appears as a child of the root {@link #AndroidManifest manifest} tag in
+         an application's manifest file. -->
     <declare-styleable name="AndroidManifestApplication" parent="AndroidManifest">
-        <!-- An optional name of a class implementing the overall
-             {@link android.app.Application} for this package.  When the
-             process for your package is started, this class is instantiated
-             before any of the other application components.  Note that this
-             is not required, and in fact most applications will probably
-             not need it. -->
+        <!-- The (optional) fully-qualified name for a subclass of
+             {@link android.app.Application} that the system instantiates before
+             any other class when an app's process starts. Most applications
+             don't need this attribute. If it's not specified, the system
+             instantiates the base Application class instead.-->
         <attr name="name" />
         <attr name="theme" />
         <attr name="label" />