Merge "Fix issue #2553553: API REVIEW: android.context.Context" into froyo

api/current.xml

@@ -34728,17 +34728,6 @@
  visibility="public"
 >
 </field>
-<field name="STORAGE_SERVICE"
- type="java.lang.String"
- transient="false"
- volatile="false"
- value="&quot;storage&quot;"
- static="true"
- final="true"
- deprecated="not deprecated"
- visibility="public"
->
-</field>
 <field name="TELEPHONY_SERVICE"
  type="java.lang.String"
  transient="false"

core/java/android/content/Context.java

@@ -417,7 +417,7 @@ public abstract class Context {
     /**
      * Returns the absolute path to the directory on the external filesystem
      * (that is somewhere on {@link android.os.Environment#getExternalStorageDirectory()
-     * Environment.getExternalStorageDirectory()} where the application can
+     * Environment.getExternalStorageDirectory()}) where the application can
      * place persistent files it owns.  These files are private to the
      * applications, and not typically visible to the user as media.
      * 
@@ -439,7 +439,7 @@ public abstract class Context {
      * {@sample development/samples/ApiDemos/src/com/example/android/apis/content/ExternalStorage.java
      * private_file}
      *
-     * <p>If you install a non-null <var>type</var> to this function, the returned
+     * <p>If you supply a non-null <var>type</var> to this function, the returned
      * file will be a path to a sub-directory of the given type.  Though these files
      * are not automatically scanned by the media scanner, you can explicitly
      * add them to the media database with
@@ -450,7 +450,7 @@ public abstract class Context {
      * Environment.getExternalStoragePublicDirectory()}, which provides
      * directories of media shared by all applications.  The
      * directories returned here are
-     * owned by the application, and its contents will be removed when the
+     * owned by the application, and their contents will be removed when the
      * application is uninstalled.  Unlike
      * {@link android.os.Environment#getExternalStoragePublicDirectory
      * Environment.getExternalStoragePublicDirectory()}, the directory
@@ -479,6 +479,7 @@ public abstract class Context {
      * this method again when it is available.
      *
      * @see #getFilesDir
+     * @see android.os.Environment#getExternalStoragePublicDirectory
      */
     public abstract File getExternalFilesDir(String type);
     
@@ -1372,6 +1373,7 @@ public abstract class Context {
     public static final String SENSOR_SERVICE = "sensor";
     
     /**
+     * @hide
      * Use with {@link #getSystemService} to retrieve a {@link
      * android.os.storage.StorageManager} for accesssing system storage
      * functions.

core/java/android/os/Environment.java

@@ -68,6 +68,15 @@ public class Environment {
      * happened.  You can determine its current state with
      * {@link #getExternalStorageState()}.
      * 
+     * <p>Applications should not directly use this top-level directory, in
+     * order to avoid polluting the user's root namespace.  Any files that are
+     * private to the application should be placed in a directory returned
+     * by {@link android.content.Context#getExternalFilesDir
+     * Context.getExternalFilesDir}, which the system will take care of deleting
+     * if the application is uninstalled.  Other shared files should be placed
+     * in one of the directories returned by
+     * {@link #getExternalStoragePublicDirectory}.
+     * 
      * <p>Here is an example of typical code to monitor the state of
      * external storage:</p>
      *