Fix issue #2553553: API REVIEW: android.context.Context
Change-Id: I3e3ab7a909329d498544dc9ed4d500cbcc4ed281
diff --git a/core/java/android/content/Context.java b/core/java/android/content/Context.java
index 2b0e7e7..ee87290 100644
--- a/core/java/android/content/Context.java
+++ b/core/java/android/content/Context.java
@@ -417,7 +417,7 @@
/**
* 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 @@
* {@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 @@
* 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 @@
* 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 static final String SENSOR_SERVICE = "sensor";
/**
+ * @hide
* Use with {@link #getSystemService} to retrieve a {@link
* android.os.storage.StorageManager} for accesssing system storage
* functions.
diff --git a/core/java/android/os/Environment.java b/core/java/android/os/Environment.java
index eab1627..f7e7d39 100644
--- a/core/java/android/os/Environment.java
+++ b/core/java/android/os/Environment.java
@@ -68,6 +68,15 @@
* 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>
*