Merge "docs: Clarified purpose of application "name" attr within manifest." into mnc-mr-docs

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
+ * Base class for maintaining global application state. You can provide your own
- * provide your own implementation by specifying its name in your
+ * implementation by creating a subclass and specifying the fully-qualified name
- * AndroidManifest.xml's <application> tag, which will cause that class
+ * of this subclass as the <code>"android:name"</code> attribute in your
- * to be instantiated for you when the process for your application/package is
+ * AndroidManifest.xml's <code>&lt;application&gt;</code> tag. The Application
- * created.
+ * 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
+ * <p class="note"><strong>Note: </strong>There is normally no need to subclass
- * most situation, static singletons can provide the same functionality in a
+ * Application.  In most situations, static singletons can provide the same
- * more modular way.  If your singleton needs a global context (for example
+ * functionality in a more modular way.  If your singleton needs a global
- * to register broadcast receivers), the function to retrieve it can be
+ * context (for example to register broadcast receivers), include
- * given a {@link android.content.Context} which internally uses
  * {@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 {
             }
         }
     }
-}
+}

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
+        <!-- The (optional) fully-qualified name for a subclass of
-             {@link android.app.Application} for this package.  When the
+             {@link android.app.Application} that the system instantiates before
-             process for your package is started, this class is instantiated
+             any other class when an app's process starts. Most applications
-             before any of the other application components.  Note that this
+             don't need this attribute. If it's not specified, the system
-             is not required, and in fact most applications will probably
+             instantiates the base Application class instead.-->
-             not need it. -->
         <attr name="name" />
         <attr name="theme" />
         <attr name="label" />