diff --git a/core/java/android/provider/DocumentsProvider.java b/core/java/android/provider/DocumentsProvider.java
index c9efb53..e35b8eb 100644
--- a/core/java/android/provider/DocumentsProvider.java
+++ b/core/java/android/provider/DocumentsProvider.java
@@ -76,9 +76,8 @@
  * only the system can obtain. Applications cannot use a documents provider
  * directly; they must go through {@link Intent#ACTION_OPEN_DOCUMENT} or
  * {@link Intent#ACTION_CREATE_DOCUMENT} which requires a user to actively
- * navigate and select documents. When a user selects documents through that
- * UI, the system issues narrow URI permission grants to the requesting
- * application.
+ * navigate and select documents. When a user selects documents through that UI,
+ * the system issues narrow URI permission grants to the requesting application.
  * </p>
  * <h3>Documents</h3>
  * <p>
@@ -91,8 +90,8 @@
  * <p>
  * Each document can have different capabilities, as described by
  * {@link Document#COLUMN_FLAGS}. For example, if a document can be represented
- * as a thumbnail, a provider can set {@link Document#FLAG_SUPPORTS_THUMBNAIL}
- * and implement
+ * as a thumbnail, your provider can set
+ * {@link Document#FLAG_SUPPORTS_THUMBNAIL} and implement
  * {@link #openDocumentThumbnail(String, Point, CancellationSignal)} to return
  * that thumbnail.
  * </p>
@@ -102,7 +101,7 @@
  * single document can be included in multiple directories when responding to
  * {@link #queryChildDocuments(String, String[], String)}. For example, a
  * provider might surface a single photo in multiple locations: once in a
- * directory of locations, and again in a directory of dates.
+ * directory of geographic locations, and again in a directory of dates.
  * </p>
  * <h3>Roots</h3>
  * <p>
@@ -162,7 +161,7 @@
 
     /**
      * Create a new document and return its newly generated
-     * {@link Document#COLUMN_DOCUMENT_ID}. A provider must allocate a new
+     * {@link Document#COLUMN_DOCUMENT_ID}. You must allocate a new
      * {@link Document#COLUMN_DOCUMENT_ID} to represent the document, which must
      * not change once returned.
      *
@@ -194,16 +193,17 @@
     }
 
     /**
-     * Return all roots currently provided. A provider must define at least one
-     * root to display to users, and it should avoid making network requests to
-     * keep this request fast.
+     * Return all roots currently provided. To display to users, you must define
+     * at least one root. You should avoid making network requests to keep this
+     * request fast.
      * <p>
      * Each root is defined by the metadata columns described in {@link Root},
      * including {@link Root#COLUMN_DOCUMENT_ID} which points to a directory
      * representing a tree of documents to display under that root.
      * <p>
      * If this set of roots changes, you must call {@link ContentResolver#notifyChange(Uri,
-     * android.database.ContentObserver)} to notify the system.
+     * android.database.ContentObserver, boolean)} with
+     * {@link DocumentsContract#buildRootsUri(String)} to notify the system.
      *
      * @param projection list of {@link Root} columns to put into the cursor. If
      *            {@code null} all supported columns should be included.
@@ -229,8 +229,8 @@
     }
 
     /**
-     * Return metadata for the single requested document. A provider should
-     * avoid making network requests to keep this request fast.
+     * Return metadata for the single requested document. You should avoid
+     * making network requests to keep this request fast.
      *
      * @param documentId the document to return.
      * @param projection list of {@link Document} columns to put into the
@@ -248,10 +248,17 @@
      * If your provider is cloud-based, and you have some data cached or pinned
      * locally, you may return the local data immediately, setting
      * {@link DocumentsContract#EXTRA_LOADING} on the Cursor to indicate that
-     * your provider is still fetching additional data. Then, when the network
-     * data is available, you can call {@link ContentResolver#notifyChange(Uri,
-     * android.database.ContentObserver)} to trigger a requery and return the
-     * complete contents.
+     * you are still fetching additional data. Then, when the network data is
+     * available, you can send a change notification to trigger a requery and
+     * return the complete contents.
+     * <p>
+     * To support change notifications, you must
+     * {@link Cursor#setNotificationUri(ContentResolver, Uri)} with a relevant
+     * Uri, such as
+     * {@link DocumentsContract#buildChildDocumentsUri(String, String)}. Then
+     * you can call {@link ContentResolver#notifyChange(Uri,
+     * android.database.ContentObserver, boolean)} with that Uri to send change
+     * notifications.
      *
      * @param parentDocumentId the directory to return children for.
      * @param projection list of {@link Document} columns to put into the
@@ -289,6 +296,20 @@
      * <p>
      * Only documents may be returned; directories are not supported in search
      * results.
+     * <p>
+     * If your provider is cloud-based, and you have some data cached or pinned
+     * locally, you may return the local data immediately, setting
+     * {@link DocumentsContract#EXTRA_LOADING} on the Cursor to indicate that
+     * you are still fetching additional data. Then, when the network data is
+     * available, you can send a change notification to trigger a requery and
+     * return the complete contents.
+     * <p>
+     * To support change notifications, you must
+     * {@link Cursor#setNotificationUri(ContentResolver, Uri)} with a relevant
+     * Uri, such as {@link DocumentsContract#buildSearchDocumentsUri(String,
+     * String, String)}. Then you can call {@link ContentResolver#notifyChange(Uri,
+     * android.database.ContentObserver, boolean)} with that Uri to send change
+     * notifications.
      *
      * @param rootId the root to search under.
      * @param query string to match documents against.
@@ -327,17 +348,14 @@
     /**
      * Open and return the requested document.
      * <p>
-     * A provider should return a reliable {@link ParcelFileDescriptor} to
+     * Your provider should return a reliable {@link ParcelFileDescriptor} to
      * detect when the remote caller has finished reading or writing the
-     * document. A provider may return a pipe or socket pair if the mode is
-     * exclusively {@link ParcelFileDescriptor#MODE_READ_ONLY} or
-     * {@link ParcelFileDescriptor#MODE_WRITE_ONLY}, but complex modes like
-     * {@link ParcelFileDescriptor#MODE_READ_WRITE} require a normal file on
-     * disk.
+     * document. You may return a pipe or socket pair if the mode is exclusively
+     * "r" or "w", but complex modes like "rw" imply a normal file on disk that
+     * supports seeking.
      * <p>
-     * If a provider blocks while downloading content, it should periodically
-     * check {@link CancellationSignal#isCanceled()} to abort abandoned open
-     * requests.
+     * If you block while downloading content, you should periodically check
+     * {@link CancellationSignal#isCanceled()} to abort abandoned open requests.
      *
      * @param documentId the document to return.
      * @param mode the mode to open with, such as 'r', 'w', or 'rw'.
@@ -359,10 +377,9 @@
      * attempting to serve from a local cache if possible. A provider should
      * never return images more than double the hinted size.
      * <p>
-     * If a provider performs expensive operations to download or generate a
-     * thumbnail, it should periodically check
-     * {@link CancellationSignal#isCanceled()} to abort abandoned thumbnail
-     * requests.
+     * If you perform expensive operations to download or generate a thumbnail,
+     * you should periodically check {@link CancellationSignal#isCanceled()} to
+     * abort abandoned thumbnail requests.
      *
      * @param documentId the document to return.
      * @param sizeHint hint of the optimal thumbnail dimensions.