JavaDoc improvements as suggested by API council. (fd59645b) · Commits · e / os / android_frameworks_base

core/java/android/preference/Preference.java

+16 −8

Original line number	Diff line number	Diff line
		@@ -410,11 +410,13 @@ public class Preference implements Comparable<Preference> {
		/**
		* Sets a {@link PreferenceDataStore} to be used by this Preference instead of using
		* {@link android.content.SharedPreferences}.
		* <p>
		* The data store will remain assigned even if the Preference is moved between multiple
		* instances of {@link PreferenceFragment}.
		*
		* <p>The data store will remain assigned even if the Preference is moved around the preference
		* hierarchy. It will also override a data store propagated from the {@link PreferenceManager}
		* that owns this Preference.
		*
		* @param dataStore The {@link PreferenceDataStore} to be used by this Preference.
		* @see PreferenceManager#setPreferenceDataStore(PreferenceDataStore)
		*/
		public void setPreferenceDataStore(PreferenceDataStore dataStore) {
		mPreferenceDataStore = dataStore;
		@@ -424,6 +426,12 @@ public class Preference implements Comparable<Preference> {
		* Returns {@link PreferenceDataStore} used by this Preference. Returns {@code null} if
		* {@link android.content.SharedPreferences} is used instead.
		*
		* <p>By default preferences always use {@link android.content.SharedPreferences}. To make this
		* preference to use the {@link PreferenceDataStore} you need to assign your implementation
		* to the Preference itself via {@link #setPreferenceDataStore(PreferenceDataStore)} or to its
		* {@link PreferenceManager} via
		* {@link PreferenceManager#setPreferenceDataStore(PreferenceDataStore)}.
		*
		* @return The {@link PreferenceDataStore} used by this Preference or {@code null} if none.
		*/
		@Nullable

core/java/android/preference/PreferenceDataStore.java

+29 −3

Original line number	Diff line number	Diff line
		@@ -21,16 +21,32 @@ import android.annotation.Nullable;
		import java.util.Set;

		/**
		* A data store interface to be implemented and provided to the Preferences framework.
		* A data store interface to be implemented and provided to the Preferences framework. This can be
		* used to replace the default {@link android.content.SharedPreferences}, if needed.
		*
		* Use this to replace the default {@link android.content.SharedPreferences}. By default, all "put"
		* methods throw {@link UnsupportedOperationException}.
		* <p>In most cases you want to use {@link android.content.SharedPreferences} as it is automatically
		* backed up and migrated to new devices. However, providing custom data store to preferences can be
		* useful if your app stores its preferences in a local db, cloud or they are device specific like
		* "Developer settings". It might be also useful when you want to use the preferences UI but
		* the data are not supposed to be stored at all because they are valid per session only.
		*
		* <p>Once a put method is called it is full responsibility of the data store implementation to
		* safely store the given values. Time expensive operations need to be done in the background to
		* prevent from blocking the UI. You also need to have a plan on how to serialize the data in case
		* the activity holding this object gets destroyed.
		*
		* <p>By default, all "put" methods throw {@link UnsupportedOperationException}.
		*
		* @see Preference#setPreferenceDataStore(PreferenceDataStore)
		* @see PreferenceManager#setPreferenceDataStore(PreferenceDataStore)
		*/
		public interface PreferenceDataStore {

		/**
		* Set a String value to the data store.
		*
		* <p>Once the value is set the data store is responsible for holding it.
		*
		* @param key The name of the preference to modify.
		* @param value The new value for the preference.
		* @see #getString(String, String)
		@@ -42,6 +58,8 @@ public interface PreferenceDataStore {
		/**
		* Set a set of String value to the data store.
		*
		* <p>Once the value is set the data store is responsible for holding it.
		*
		* @param key The name of the preference to modify.
		* @param values The set of new values for the preference.
		* @see #getStringSet(String, Set)
		@@ -53,6 +71,8 @@ public interface PreferenceDataStore {
		/**
		* Set an int value to the data store.
		*
		* <p>Once the value is set the data store is responsible for holding it.
		*
		* @param key The name of the preference to modify.
		* @param value The new value for the preference.
		* @see #getInt(String, int)
		@@ -64,6 +84,8 @@ public interface PreferenceDataStore {
		/**
		* Set a long value to the data store.
		*
		* <p>Once the value is set the data store is responsible for holding it.
		*
		* @param key The name of the preference to modify.
		* @param value The new value for the preference.
		* @see #getLong(String, long)
		@@ -75,6 +97,8 @@ public interface PreferenceDataStore {
		/**
		* Set a float value to the data store.
		*
		* <p>Once the value is set the data store is responsible for holding it.
		*
		* @param key The name of the preference to modify.
		* @param value The new value for the preference.
		* @see #getFloat(String, float)
		@@ -86,6 +110,8 @@ public interface PreferenceDataStore {
		/**
		* Set a boolean value to the data store.
		*
		* <p>Once the value is set the data store is responsible for holding it.
		*
		* @param key The name of the preference to modify.
		* @param value The new value for the preference.
		* @see #getBoolean(String, boolean)

core/java/android/preference/PreferenceManager.java

+10 −3

Original line number	Diff line number	Diff line
		@@ -208,10 +208,13 @@ public class PreferenceManager {

		/**
		* Sets a {@link PreferenceDataStore} to be used by all Preferences associated with this manager
		* that don't have a custom {@link PreferenceDataStore} assigned. Also if the data store is set,
		* the Preferences will no longer use {@link android.content.SharedPreferences}.
		* that don't have a custom {@link PreferenceDataStore} assigned via
		* {@link Preference#setPreferenceDataStore(PreferenceDataStore)}. Also if the data store is
		* set, the child preferences won't use {@link android.content.SharedPreferences} as long as
		* they are assigned to this manager.
		*
		* @param dataStore The {@link PreferenceDataStore} to be used by this manager.
		* @see Preference#setPreferenceDataStore(PreferenceDataStore)
		*/
		public void setPreferenceDataStore(PreferenceDataStore dataStore) {
		mPreferenceDataStore = dataStore;
		@@ -219,9 +222,10 @@ public class PreferenceManager {

		/**
		* Returns the {@link PreferenceDataStore} associated with this manager or {@code null} if
		* {@link android.content.SharedPreferences} are used instead.
		* the default {@link android.content.SharedPreferences} are used instead.
		*
		* @return The {@link PreferenceDataStore} associated with this manager or {@code null} if none.
		* @see #setPreferenceDataStore(PreferenceDataStore)
		*/
		@Nullable
		public PreferenceDataStore getPreferenceDataStore() {
		@@ -358,8 +362,11 @@ public class PreferenceManager {
		* Sets the name of the SharedPreferences file that preferences managed by this
		* will use.
		*
		* <p>If custom {@link PreferenceDataStore} is set, this won't override its usage.
		*
		* @param sharedPreferencesName The name of the SharedPreferences file.
		* @see Context#getSharedPreferences(String, int)
		* @see #setPreferenceDataStore(PreferenceDataStore)
		*/
		public void setSharedPreferencesName(String sharedPreferencesName) {
		mSharedPreferencesName = sharedPreferencesName;