From acaf028fc9efd9754f57ed65476e79a816811b35 Mon Sep 17 00:00:00 2001
From: Dianne Hackborn <hackbod@google.com>
Date: Tue, 30 Mar 2010 14:39:35 -0700
Subject: [PATCH] Fix issue #2553553: API REVIEW: android.context.Context

Change-Id: I3e3ab7a909329d498544dc9ed4d500cbcc4ed281
---
 api/current.xml                        | 11 -----------
 core/java/android/content/Context.java |  8 +++++---
 core/java/android/os/Environment.java  |  9 +++++++++
 3 files changed, 14 insertions(+), 14 deletions(-)

diff --git a/api/current.xml b/api/current.xml
index aea02e53c5d4d..9151b84060573 100644
--- a/api/current.xml
+++ b/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"
diff --git a/core/java/android/content/Context.java b/core/java/android/content/Context.java
index 2b0e7e7456d89..ee872903e4436 100644
--- a/core/java/android/content/Context.java
+++ b/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.
diff --git a/core/java/android/os/Environment.java b/core/java/android/os/Environment.java
index eab16275cb9cd..f7e7d39954527 100644
--- a/core/java/android/os/Environment.java
+++ b/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>
      *