Cleans up Javadoc and adds package-info.java
Bug: b/119613725
Test: n/a
Change-Id: I018fd9d7709b950f02341b76e8e2cd35449c810b
diff --git a/preference/src/main/java/androidx/preference/Preference.java b/preference/src/main/java/androidx/preference/Preference.java
index 2a1ac4a..3ce5829 100644
--- a/preference/src/main/java/androidx/preference/Preference.java
+++ b/preference/src/main/java/androidx/preference/Preference.java
@@ -48,29 +48,27 @@
import androidx.appcompat.content.res.AppCompatResources;
import androidx.core.content.res.TypedArrayUtils;
import androidx.core.view.accessibility.AccessibilityNodeInfoCompat;
-import androidx.recyclerview.widget.RecyclerView;
import java.util.ArrayList;
import java.util.List;
import java.util.Set;
/**
- * Represents the basic {@link Preference} UI building block displayed by a
- * {@link PreferenceFragmentCompat} in the form of a {@link RecyclerView}. This class provides
- * data for the {@link android.view.View} to be displayed in the list and associates with a
- * {@link SharedPreferences} or {@link PreferenceDataStore} to store/retrieve the preference data.
+ * The basic building block that represents an individual setting displayed to a user in the
+ * preference hierarchy. This class provides the data that will be displayed to the user and has
+ * a reference to the {@link SharedPreferences} or {@link PreferenceDataStore} instance that
+ * persists the preference's values.
*
* <p>When specifying a preference hierarchy in XML, each element can point to a subclass of
* {@link Preference}, similar to the view hierarchy and layouts.
*
- * <p>This class contains a {@code key} that will be used as the key into the
- * {@link SharedPreferences}. It is up to the subclass to decide how to store the value.
+ * <p>This class contains a {@code key} that that represents the key that is used to persist the
+ * value to the device. It is up to the subclass to decide how to store the value.
*
* <div class="special reference">
* <h3>Developer Guides</h3>
- * <p>For information about building a settings UI with Preferences,
- * read the <a href="{@docRoot}guide/topics/ui/settings.html">Settings</a>
- * guide.</p>
+ * <p>For information about building a settings screen using the AndroidX Preference library, see
+ * <a href="{@docRoot}guide/topics/ui/settings.html">Settings</a>.</p>
* </div>
*
* @attr name android:icon
diff --git a/preference/src/main/java/androidx/preference/PreferenceCategory.java b/preference/src/main/java/androidx/preference/PreferenceCategory.java
index d2252ef..258edae 100644
--- a/preference/src/main/java/androidx/preference/PreferenceCategory.java
+++ b/preference/src/main/java/androidx/preference/PreferenceCategory.java
@@ -29,14 +29,13 @@
import androidx.core.view.accessibility.AccessibilityNodeInfoCompat.CollectionItemInfoCompat;
/**
- * Used to group {@link Preference} objects and provide a disabled title above
- * the group.
+ * A container that is used to group similar {@link Preference}s. A PreferenceCategory displays a
+ * category title and visually separates groups of Preferences.
*
* <div class="special reference">
* <h3>Developer Guides</h3>
- * <p>For information about building a settings UI with Preferences,
- * read the <a href="{@docRoot}guide/topics/ui/settings.html">Settings</a>
- * guide.</p>
+ * <p>For information about building a settings screen using the AndroidX Preference library, see
+ * <a href="{@docRoot}guide/topics/ui/settings.html">Settings</a>.</p>
* </div>
*/
public class PreferenceCategory extends PreferenceGroup {
diff --git a/preference/src/main/java/androidx/preference/PreferenceFragment.java b/preference/src/main/java/androidx/preference/PreferenceFragment.java
index 83f490c..14e0d8b 100644
--- a/preference/src/main/java/androidx/preference/PreferenceFragment.java
+++ b/preference/src/main/java/androidx/preference/PreferenceFragment.java
@@ -82,8 +82,8 @@
*
* <div class="special reference">
* <h3>Developer Guides</h3>
- * <p>For information about using {@code PreferenceFragment}, read the
- * <a href="{@docRoot}guide/topics/ui/settings.html">Settings</a> guide.</p>
+ * <p>For information about building a settings screen using the AndroidX Preference library, see
+ * <a href="{@docRoot}guide/topics/ui/settings.html">Settings</a>.</p>
* </div>
*
* @see Preference
diff --git a/preference/src/main/java/androidx/preference/PreferenceFragmentCompat.java b/preference/src/main/java/androidx/preference/PreferenceFragmentCompat.java
index 533fe5e..eb3bf69 100644
--- a/preference/src/main/java/androidx/preference/PreferenceFragmentCompat.java
+++ b/preference/src/main/java/androidx/preference/PreferenceFragmentCompat.java
@@ -18,6 +18,7 @@
import static androidx.annotation.RestrictTo.Scope.LIBRARY_GROUP;
+import android.content.Context;
import android.content.pm.PackageManager;
import android.content.res.TypedArray;
import android.graphics.Canvas;
@@ -44,59 +45,43 @@
import androidx.recyclerview.widget.RecyclerView;
/**
- * Shows a hierarchy of {@link Preference} objects as lists. These preferences will automatically
- * save to {@link android.content.SharedPreferences} as the user interacts with them. To retrieve
- * an instance of {@link android.content.SharedPreferences} that the preference hierarchy in this
- * fragment will use, call
+ * A PreferenceFragmentCompat is the entry point to using the Preference library. This
+ * {@link Fragment} displays a hierarchy of {@link Preference} objects to the user. It also
+ * handles persisting values to the device. To retrieve an instance of
+ * {@link android.content.SharedPreferences} that the preference hierarchy in this fragment will
+ * use by default, call
* {@link PreferenceManager#getDefaultSharedPreferences(android.content.Context)} with a context
* in the same package as this fragment.
*
- * <p>Furthermore, the preferences shown will follow the visual style of system preferences. It
- * is easy to create a hierarchy of preferences (that can be shown on multiple screens) via XML.
- * For these reasons, it is recommended to use this fragment (as a superclass) to deal with
- * preferences in applications.
+ * <p>You can define a preference hierarchy as an XML resource, or you can build a hierarchy in
+ * code. In both cases you need to use a {@link PreferenceScreen} as the root component in your
+ * hierarchy.
*
- * <p>A {@link PreferenceScreen} object should be at the top of the preference hierarchy.
- * Furthermore, subsequent {@link PreferenceScreen} in the hierarchy denote a screen break--that
- * is the preferences contained within subsequent {@link PreferenceScreen} should be shown on
- * another screen. The preference framework handles this by calling
- * {@link #onNavigateToScreen(PreferenceScreen)}.
+ * <p>To inflate from XML, use the {@link #setPreferencesFromResource(int, String)}. An example
+ * example XML resource is shown further down.
*
- * <p>The preference hierarchy can be formed in multiple ways:
- *
- * <li> From an XML file specifying the hierarchy
- * <li> From different {@link android.app.Activity Activities} that each specify its own
- * preferences in an XML file via {@link android.app.Activity} meta-data
- * <li> From an object hierarchy rooted with {@link PreferenceScreen}
- *
- * <p>To inflate from XML, use the {@link #addPreferencesFromResource(int)}. The root element
- * should be a {@link PreferenceScreen}. Subsequent elements can point to actual
- * {@link Preference} subclasses. As mentioned above, subsequent {@link PreferenceScreen} in the
- * hierarchy will result in the screen break.
- *
- * <p>To specify an object hierarchy rooted with {@link PreferenceScreen}, use
- * {@link #setPreferenceScreen(PreferenceScreen)}.
+ * <p>To build a hierarchy from code, use
+ * {@link PreferenceManager#createPreferenceScreen(Context)} to create the root
+ * {@link PreferenceScreen}. Once you have added other {@link Preference}s to this root scree
+ * with {@link PreferenceScreen#addPreference(Preference)}, you then need to set the screen as
+ * the root screen in your hierarchy with {@link #setPreferenceScreen(PreferenceScreen)}.
*
* <p>As a convenience, this fragment implements a click listener for any preference in the
* current hierarchy, see {@link #onPreferenceTreeClick(Preference)}.
*
- * <div class="special reference">
- * <h3>Developer Guides</h3>
- * <p>For information about using {@link PreferenceFragmentCompat}, read the
- * <a href="{@docRoot}guide/topics/ui/settings.html">Settings</a> guide.</p>
- * </div>
+ * <div class="special reference"> <h3>Developer Guides</h3> <p>For more information about
+ * building a settings screen using the AndroidX Preference library, see
+ * <a href="{@docRoot}guide/topics/ui/settings.html">Settings</a>.</p> </div>
*
* <a name="SampleCode"></a>
* <h3>Sample Code</h3>
*
- * <p>The following sample code shows a simple preference fragment that is
- * populated from a resource. The resource it loads is:</p>
+ * <p>The following sample code shows a simple settings screen using an XML resource. The XML
+ * resource is as follows:</p>
*
* {@sample frameworks/support/samples/SupportPreferenceDemos/src/main/res/xml/preferences.xml preferences}
*
- * <p>The fragment implementation itself simply populates the preferences
- * when created. Note that the preferences framework takes care of loading
- * the current values out of the app preferences and writing them when changed:</p>
+ * <p>The fragment that loads the XML resource is as follows:</p>
*
* {@sample frameworks/support/samples/SupportPreferenceDemos/src/main/java/com/example/androidx/preference/Preferences.java preferences}
*
diff --git a/preference/src/main/java/androidx/preference/PreferenceGroup.java b/preference/src/main/java/androidx/preference/PreferenceGroup.java
index e2d888c..1e89caf 100644
--- a/preference/src/main/java/androidx/preference/PreferenceGroup.java
+++ b/preference/src/main/java/androidx/preference/PreferenceGroup.java
@@ -39,14 +39,13 @@
import java.util.List;
/**
- * A container for multiple {@link Preference} objects. It is a base class for preference
+ * A container for multiple {@link Preference}s. It is a base class for preference
* objects that are parents, such as {@link PreferenceCategory} and {@link PreferenceScreen}.
*
* <div class="special reference">
* <h3>Developer Guides</h3>
- * <p>For information about building a settings UI with Preferences,
- * read the <a href="{@docRoot}guide/topics/ui/settings.html">Settings</a>
- * guide.</p>
+ * <p>For information about building a settings screen using the AndroidX Preference library, see
+ * <a href="{@docRoot}guide/topics/ui/settings.html">Settings</a>.</p>
* </div>
*
* @attr name android:orderingFromXml
diff --git a/preference/src/main/java/androidx/preference/PreferenceScreen.java b/preference/src/main/java/androidx/preference/PreferenceScreen.java
index 0de6b943..d2cd75c 100644
--- a/preference/src/main/java/androidx/preference/PreferenceScreen.java
+++ b/preference/src/main/java/androidx/preference/PreferenceScreen.java
@@ -25,54 +25,17 @@
import androidx.core.content.res.TypedArrayUtils;
/**
- * Represents a top-level {@link Preference} that is the root of a preference hierarchy. A
- * {@link PreferenceFragmentCompat} points to an instance of this class to show the preferences.
- * To instantiate this class, use {@link PreferenceManager#createPreferenceScreen(Context)}.
- *
- * <ul> This class can appear in two places:
- * <li> When a {@link PreferenceFragmentCompat} points to this, it is used as the root and is not
- * shown (only the contained preferences are shown).
- * <li> When it appears inside another preference hierarchy, it is shown and serves as the
- * gateway to another screen of preferences (either by showing another screen of preferences as a
- * {@link android.app.Dialog} or via a {@link Context#startActivity(android.content.Intent)} from
- * the {@link Preference#getIntent()}). The children of this {@link PreferenceScreen} are NOT
- * shown in the screen that this {@link PreferenceScreen} is shown in. Instead, a separate screen
- * will be shown when this preference is clicked.
- * </ul>
- *
- * <p>Here's an example XML layout of a PreferenceScreen:</p>
- * <pre>
- * <PreferenceScreen
- * xmlns:android="http://schemas.android.com/apk/res/android"
- * android:key="first_preferencescreen">
- * <CheckBoxPreference
- * android:key="wifi enabled"
- * android:title="WiFi" />
- * <PreferenceScreen
- * android:key="second_preferencescreen"
- * android:title="WiFi settings">
- * <CheckBoxPreference
- * android:key="prefer wifi"
- * android:title="Prefer WiFi" />
- * ... other preferences here ...
- * </PreferenceScreen>
- * </PreferenceScreen> </pre>
- * <p>
- *
- * In this example, the "first_preferencescreen" will be used as the root of the hierarchy and
- * given to a {@link PreferenceFragmentCompat}. The first screen will show preferences "WiFi"
- * (which can be used to quickly enable/disable WiFi) and "WiFi settings". The "WiFi settings" is
- * the "second_preferencescreen" and when clicked will show another screen of preferences such as
- * "Prefer WiFi" (and the other preferences that are children of the "second_preferencescreen" tag).
+ * A top-level container that represents a settings screen. This is the root component of your
+ * {@link Preference} hierarchy. A {@link PreferenceFragmentCompat} points to an instance of this
+ * class to show the preferences. To instantiate this class, use
+ * {@link PreferenceManager#createPreferenceScreen(Context)}.
*
* <div class="special reference">
* <h3>Developer Guides</h3>
- * <p>For information about building a settings UI with Preferences,
- * read the <a href="{@docRoot}guide/topics/ui/settings.html">Settings</a>
- * guide.</p>
+ * <p>For information about building a settings screen using the AndroidX Preference library, see
+ * <a href="{@docRoot}guide/topics/ui/settings.html">Settings</a>.</p>
* </div>
*
- * @see PreferenceCategory
*/
public final class PreferenceScreen extends PreferenceGroup {
diff --git a/preference/src/main/java/androidx/preference/package-info.java b/preference/src/main/java/androidx/preference/package-info.java
new file mode 100644
index 0000000..2fdcdad
--- /dev/null
+++ b/preference/src/main/java/androidx/preference/package-info.java
@@ -0,0 +1,28 @@
+/*
+ * Copyright 2018 The Android Open Source Project
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/**
+ * The Preference library allows you to build interactive settings screens, without needing to
+ * handle interacting with device storage or managing the user interface.
+ *
+ * <div class="special reference">
+ * <h3>Developer Guides</h3>
+ * <p>For information about building a settings screen using the AndroidX Preference library, see
+ * <a href="{@docRoot}guide/topics/ui/settings.html">Settings</a>.</p>
+ * </div>
+ */
+
+package androidx.preference;
