docs: further clarify the behavior of targetSdkVersion

bug: 5854083

Change-Id: I913a245b754604165b4570447f797f7cc66af5f9

1 files changed, 36 insertions, 22 deletions

diff --git a/docs/html/guide/topics/manifest/uses-sdk-element.jd b/docs/html/guide/topics/manifest/uses-sdk-element.jd
index b371f34..99c91f6 100644
--- a/docs/html/guide/topics/manifest/uses-sdk-element.jd
+++ b/docs/html/guide/topics/manifest/uses-sdk-element.jd
@@ -60,7 +60,7 @@ href="{@docRoot}guide/appendix/market-filters.html">Market Filters</a>.</p>
   attribute, the system assumes a default value of "1", which indicates that your
   application is compatible with all versions of Android. If your application is
   <em>not</em> compatible with all versions (for instance, it uses APIs introduced
-  in API Level 3) and you have not declared the proper <code>android:minSdkVersion</code>,
+  in API Level 3) and you have not declared the proper <code>minSdkVersion</code>,
   then when installed on a system with an API Level less than 3, the application
   will crash during runtime when attempting to access the unavailable APIs. For
   this reason, be certain to declare the appropriate API Level in the
@@ -68,18 +68,32 @@ href="{@docRoot}guide/appendix/market-filters.html">Market Filters</a>.</p>
   </dd>
 
   <dt><a name="target"></a>{@code android:targetSdkVersion}</dt>
-  <dd>An integer designating the API Level that the application is targetting.
-
-  <p>With this attribute set, the application says that it is able to run on
-  older versions (down to {@code minSdkVersion}), but was explicitly tested to
-  work with the version specified here. Specifying this target version allows the
-  platform to disable compatibility settings that are not required for the target
-  version (which may otherwise be turned on in order to maintain
-  forward-compatibility) or enable newer features that are not available to older
-  applications. This does not mean that you can program different features for
-  different versions of the platform&mdash;it simply informs the platform that you
-  have tested against the target version and the platform should not perform any
-  extra work to maintain forward-compatibility with the target version.</p>
+  <dd>An integer designating the API Level that the application targets. If not set, the default
+value equals that given to {@code minSdkVersion}.
+
+  <p>This attribute informs the system that you have tested against the target version and the
+system should not enable any compatibility behaviors to maintain your app's forward-compatibility
+with the target version. The application is still able to run on older versions (down to {@code
+minSdkVersion}).</p>
+
+  <p>As Android evolves with each new version, some behaviors and even appearances might change.
+However, if the API level of the platform is higher than the version declared by your app's {@code
+targetSdkVersion}, the system may enable compatibility behaviors to ensure that your app
+continues to work the way you expect. You can disable such compatibility
+behaviors by specifying {@code targetSdkVersion} to match the API
+level of the platform on which it's running. For example, setting this value to "11" or higher
+allows the system to apply a new default theme (Holo) to your app when running on Android 3.0 or
+higher and also disables <a href="{@docRoot}guide/practices/screen-compat-mode.html">screen
+compatibility mode</a> when running on larger screens (because support for API level 11 implicitly
+supports larger screens).</p>
+
+  <p>There are many compatibility behaviors that the system may enable based on the value you set
+for this attribute. Several of these behaviors are described by the corresponding platform versions
+in the {@link android.os.Build.VERSION_CODES} reference.</p>
+
+  <p>To maintain your application along with each Android release, you should increase
+the value of this attribute to match the latest API level, then thoroughly test your application on
+the corresponding platform version.</p>
 
   <p>Introduced in: API Level 4</p>
   </dd>
@@ -89,25 +103,25 @@ href="{@docRoot}guide/appendix/market-filters.html">Market Filters</a>.</p>
   designed to run. 
 
   <p>In Android 1.5, 1.6, 2.0, and 2.0.1, the system checks the value of this
-  attribute when installing an application and when revalidating the application
+  attribute when installing an application and when re-validating the application
   after a system update. In either case, if the application's
-  <code>android:maxSdkVersion</code> attribute is lower than the API Level used by
+  <code>maxSdkVersion</code> attribute is lower than the API Level used by
   the system itself, then the system will not allow the application to be
-  installed. In the case of revalidation after system update, this effectively
+  installed. In the case of re-validation after system update, this effectively
   removes your application from the device.
 
   <p>To illustrate how this attribute can affect your application after system
   updates, consider the following example: </p>
 
-  <p>An application declaring <code>android:maxSdkVersion="5"</code> in its
+  <p>An application declaring <code>maxSdkVersion="5"</code> in its
   manifest is published on Android Market. A user whose device is running Android
   1.6 (API Level 4) downloads and installs the app. After a few weeks, the user
   receives an over-the-air system update to Android 2.0 (API Level 5). After the
   update is installed, the system checks the application's
-  <code>android:maxSdkVersion</code> and successfully revalidates it. The
+  <code>maxSdkVersion</code> and successfully re-validates it. The
   application functions as normal. However, some time later, the device receives
   another system update, this time to Android 2.0.1 (API Level 6). After the
-  update, the system can no longer revalidate the application because the system's
+  update, the system can no longer re-validate the application because the system's
   own API Level (6) is now higher than the maximum supported by the application
   (5). The system prevents the application from being visible to the user, in
   effect removing it from the device.</p>
@@ -120,7 +134,7 @@ href="{@docRoot}guide/appendix/market-filters.html">Market Filters</a>.</p>
   provided it uses only standard APIs and follows development best practices.
   Second, note that in some cases, declaring the attribute can <strong>result in
   your application being removed from users' devices after a system
-  update</strong> to a higher API Level. Most devices on which your appplication
+  update</strong> to a higher API Level. Most devices on which your application
   is likely to be installed will receive periodic system updates over the air, so
   you should consider their effect on your application before setting this
   attribute.</p>
@@ -128,8 +142,8 @@ href="{@docRoot}guide/appendix/market-filters.html">Market Filters</a>.</p>
   <p style="margin-bottom:1em;">Introduced in: API Level 4</p>
 
   <div class="special">Future versions of Android (beyond Android 2.0.1) will no
-longer check or enforce the <code>android:maxSdkVersion</code> attribute during
-installation or revalidation. Android Market will continue to use the attribute
+longer check or enforce the <code>maxSdkVersion</code> attribute during
+installation or re-validation. Android Market will continue to use the attribute
 as a filter, however, when presenting users with applications available for
 download. </div>
   </dd>