am db242310: Merge "docs: add Settings dev guide; a few changes to javadocs" into jb-dev

* commit 'db24231057bdf8b11a10c772084cfc0e4294ec04':
  docs: add Settings dev guide; a few changes to javadocs

1 files changed, 28 insertions, 8 deletions

diff --git a/core/java/android/preference/PreferenceManager.java b/core/java/android/preference/PreferenceManager.java
index 6562de90a3c8..5ca7d79c1394 100644
--- a/core/java/android/preference/PreferenceManager.java
+++ b/core/java/android/preference/PreferenceManager.java
@@ -415,19 +415,20 @@ public class PreferenceManager {
     }
     
     /**
-     * Sets the default values from a preference hierarchy in XML. This should
+     * Sets the default values from an XML preference file by reading the values defined
+     * by each {@link Preference} item's {@code android:defaultValue} attribute. This should
      * be called by the application's main activity.
      * <p>
-     * If {@code readAgain} is false, this will only set the default values if this
-     * method has never been called in the past (or the
-     * {@link #KEY_HAS_SET_DEFAULT_VALUES} in the default value shared
-     * preferences file is false). To attempt to set the default values again
-     * bypassing this check, set {@code readAgain} to true.
      * 
      * @param context The context of the shared preferences.
-     * @param resId The resource ID of the preference hierarchy XML file.
+     * @param resId The resource ID of the preference XML file.
      * @param readAgain Whether to re-read the default values.
-     *            <p>
+     * If false, this method sets the default values only if this
+     * method has never been called in the past (or if the
+     * {@link #KEY_HAS_SET_DEFAULT_VALUES} in the default value shared
+     * preferences file is false). To attempt to set the default values again
+     * bypassing this check, set {@code readAgain} to true.
+     *            <p class="note">
      *            Note: this will NOT reset preferences back to their default
      *            values. For that functionality, use
      *            {@link PreferenceManager#getDefaultSharedPreferences(Context)}
@@ -445,6 +446,25 @@ public class PreferenceManager {
      * Similar to {@link #setDefaultValues(Context, int, boolean)} but allows
      * the client to provide the filename and mode of the shared preferences
      * file.
+     *
+     * @param context The context of the shared preferences.
+     * @param sharedPreferencesName A custom name for the shared preferences file.
+     * @param sharedPreferencesMode The file creation mode for the shared preferences file, such
+     * as {@link android.content.Context#MODE_PRIVATE} or {@link
+     * android.content.Context#MODE_PRIVATE}
+     * @param resId The resource ID of the preference XML file.
+     * @param readAgain Whether to re-read the default values.
+     * If false, this method will set the default values only if this
+     * method has never been called in the past (or if the
+     * {@link #KEY_HAS_SET_DEFAULT_VALUES} in the default value shared
+     * preferences file is false). To attempt to set the default values again
+     * bypassing this check, set {@code readAgain} to true.
+     *            <p class="note">
+     *            Note: this will NOT reset preferences back to their default
+     *            values. For that functionality, use
+     *            {@link PreferenceManager#getDefaultSharedPreferences(Context)}
+     *            and clear it followed by a call to this method with this
+     *            parameter set to true.
      * 
      * @see #setDefaultValues(Context, int, boolean)
      * @see #setSharedPreferencesName(String)