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

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
+     * 
+     * @param context The context of the shared preferences.
+     * @param resId The resource ID of the preference XML file.
+     * @param readAgain Whether to re-read the default values.
+     * 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.
-     * 
-     * @param context The context of the shared preferences.
-     * @param resId The resource ID of the preference hierarchy XML file.
-     * @param readAgain Whether to re-read the default values.
-     *            <p>
+     *            <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)

docs/html/guide/components/fragments.jd

@@ -709,6 +709,12 @@ href="{@docRoot}guide/components/activities.html#Lifecycle">managing the activit
 lifecycle</a> also apply to fragments. What you also need to understand, though, is how the life
 of the activity affects the life of the fragment.</p>
 
+<p class="caution"><strong>Caution:</strong> If you need a {@link android.content.Context} object
+within your {@link android.app.Fragment}, you can call {@link android.app.Fragment#getActivity()}.
+However, be careful to call {@link android.app.Fragment#getActivity()} only when the fragment is
+attached to an activity. When the fragment is not yet attached, or was detached during the end of
+its lifecycle, {@link android.app.Fragment#getActivity()} will return null.</p>
+
 
 <h3 id="CoordinatingWithActivity">Coordinating with the activity lifecycle</h3>
 

docs/html/guide/guide_toc.cs

@@ -197,6 +197,9 @@
       <li><a href="<?cs var:toroot ?>guide/topics/ui/actionbar.html">
            <span class="en">Action Bar</span>
           </a></li>
+      <li><a href="<?cs var:toroot ?>guide/topics/ui/settings.html">
+            <span class="en">Settings</span>
+          </a></li>
       <li class="nav-section">
           <div class="nav-section-header"><a href="<?cs var:toroot ?>guide/topics/ui/notifiers/index.html">
               <span class="en">Notifications</span>