Add JavaDoc for new @PreferenceXXX annotations

yDelouis · Apr 25, 2015 · Sep 23, 2014 · Sep 23, 2014 · Sep 24, 2014 · Sep 24, 2014
commit 502a55548a437107206b9bd4ee453a985345c8bb
diff --git a/...oidannotations-api/src/main/java/org/androidannotations/annotations/AfterPreferences.java b/...oidannotations-api/src/main/java/org/androidannotations/annotations/AfterPreferences.java
@@ -20,6 +20,44 @@
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
+/**
+ * <p>
+ * Methods annotated with {@link AfterPreferences} will be called after
+ * <code>addPreferenceFromResource</code> is called by the generated classs.
+ * </p>
+ * <p>
+ * This occurs AFTER <code>addPreferencesFromResource</code> which is called at
+ * the end of super.onCreate(). Any preference depending code should be done in
+ * an {@link AfterPreferences} annotated method.
+ * </p>
+ * <p>
+ * The method MUST have zero parameters.
+ * </p>
+ * <p>
+ * There MAY be several methods annotated with {@link AfterPreferences} in the
+ * same class.
+ * </p>
+ * <blockquote>
+ *
+ * Example :
+ *
+ * <pre>
+ * &#064;EActivity
+ * public class SettingsActivity extends PreferenceActivity {
+ * 
+ * 	&#064;PreferenceByKey(R.string.checkBoxPref)
+ * 	CheckBoxPreference checkBoxPref;
+ * 
+ * 	&#064;AfterPreferences
+ * 	void initPrefs() {
+ * 		checkBoxPref.setChecked(false);
+ * 	}
+ * }
+ * </pre>
+ *
+ * </blockquote>
+ * 
+ */
 @Retention(RetentionPolicy.CLASS)
 @Target(ElementType.METHOD)
 public @interface AfterPreferences {

diff --git a/...roidannotations-api/src/main/java/org/androidannotations/annotations/PreferenceByKey.java b/...roidannotations-api/src/main/java/org/androidannotations/annotations/PreferenceByKey.java
@@ -20,6 +20,48 @@
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
+/**
+ * <p>
+ * Use it on a {@link android.preference.Preference Preference} or
+ * {@link android.preference.Preference Preference} subtype fields in a
+ * {@link org.androidannotations.annotations.EActivity EActivity} or
+ * {@link org.androidannotations.annotations.EFragment EFragment} annotated
+ * class, which is a subclass of {@link android.preference.PreferenceActivity
+ * PreferenceActivity} or <code>PreferenceFragment</code>, respectively.
+ * </p>
+ * <p>
+ * The annotation value should be an array of R.string.* fields.
+ * </p>
+ * <p>
+ * Your code related to injected views should go in an
+ * {@link org.androidannotations.annotations.AfterPreferences AfterPreferences}
+ * annotated method.
+ * </p>
+ * <blockquote>
+ *
+ * Example :
+ *
+ * <pre>
+ * &#064;EActivity
+ * public class SettingsActivity extends PreferenceActivity {
+ * 
+ * 	&#064;PreferenceByKey(R.string.myPref1)
+ * 	Preference myPreference1;
+ * 
+ * 	&#064;PreferenceByKey(R.string.checkBoxPref)
+ * 	CheckBoxPreference checkBoxPref;
+ * 
+ * 	&#064;AfterPreferences
+ * 	void initPrefs() {
+ * 		checkBoxPref.setChecked(false);
+ * 	}
+ * }
+ * </pre>
+ *
+ * </blockquote>
+ *
+ * @see org.androidannotations.annotations.AfterPreferences AfterPreferences
+ */
 @Retention(RetentionPolicy.CLASS)
 @Target(ElementType.FIELD)
 public @interface PreferenceByKey {

diff --git a/...oidannotations-api/src/main/java/org/androidannotations/annotations/PreferenceChange.java b/...oidannotations-api/src/main/java/org/androidannotations/annotations/PreferenceChange.java
@@ -20,6 +20,61 @@
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
+/**
+ * <p>
+ * This annotation is intended to be used on methods to receive events defined
+ * by
+ * {@link android.preference.Preference.OnPreferenceChangeListener#onPreferenceChange(android.preference.Preference, Object)
+ * OnPreferenceChangeListener#onPreferenceChange} when the value of a
+ * {@link android.preference.Preference Preference} has been changed by the user
+ * and is about to be set and/or persisted.
+ * </p>
+ * <p>
+ * The annotation value should be one or several R.string.* fields that refers
+ * to {@link android.preference.Preference Preference} or subclasses of
+ * {@link android.preference.Preference Preference}. If not set, the method name
+ * will be used as the R.string.* field name.
+ * </p>
+ * <p>
+ * The method MAY have multiple parameter:
+ * </p>
+ * <ul>
+ * <li>A {@link android.preference.Preference Preference} parameter to know
+ * which preference was targeted by this event</li>
+ * <li>An {@link Object} or {@link java.util.Set Set of strings} or
+ * {@link Boolean} or {@link String} to obtain the new value of the
+ * {@link android.preference.Preference Preference}</li>
+ * </ul>
+ * <blockquote>
+ * 
+ * Example :
+ * 
+ * <pre>
+ * &#064;PreferenceChange(<b>R.string.myPref</b>)
+ * void checkedChangedOnMyButton(boolean newValue, Preference preference) {
+ * 	// Something Here
+ * }
+ * 
+ * &#064;PreferenceChange
+ * void <b>myPref</b>PreferenceChanged(Preference preference) {
+ * 	// Something Here
+ * }
+ * 
+ * &#064;PreferenceChange(<b>{R.string.myPref1, R.string.myPref2}</b>)
+ * void preferenceChangeOnMultiplePrefs(Preference preference, String newValue) {
+ * 	// Something Here
+ * }
+ * 
+ * &#064;PreferenceChange(<b>R.string.myPref</b>)
+ * void preferenceChangeOnMyPref() {
+ * 	// Something Here
+ * }
+ * </pre>
+ * 
+ * </blockquote>
+ * 
+ * @see PreferenceClick
+ */
 @Retention(RetentionPolicy.CLASS)
 @Target(ElementType.METHOD)
 public @interface PreferenceChange {

diff --git a/...roidannotations-api/src/main/java/org/androidannotations/annotations/PreferenceClick.java b/...roidannotations-api/src/main/java/org/androidannotations/annotations/PreferenceClick.java
@@ -20,6 +20,46 @@
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
+/**
+ * <p>
+ * This annotation is intended to be used on methods to receive events defined
+ * by
+ * {@link android.preference.Preference.OnPreferenceClickListener#onPreferenceClick(android.preference.Preference)
+ * OnPreferenceClickListener#onPreferenceClick} when the
+ * {@link android.preference.Preference Preference} has been clicked by the
+ * user.
+ * </p>
+ * <p>
+ * The annotation value should be one or several of R.string.* fields. If not
+ * set, the method name will be used as the R.string.* field name.
+ * </p>
+ * <p>
+ * The method MAY have one parameter:
+ * </p>
+ * <ul>
+ * <li>A {@link android.preference.Preference Preference} parameter to know
+ * which preference has been clicked</li>
+ * </ul>
+ * <blockquote>
+ * 
+ * Example :
+ * 
+ * <pre>
+ * &#064;PreferenceClick(<b>R.string.myPref</b>)
+ * void clickOnMyPref() {
+ * 	// Something Here
+ * }
+ * 
+ * &#064;PreferenceClick
+ * void <b>myPref</b>PreferenceClicked(Preference preference) {
+ * 	// Something Here
+ * }
+ * </pre>
+ * 
+ * </blockquote>
+ * 
+ * @see PreferenceChange
+ */
 @Retention(RetentionPolicy.CLASS)
 @Target(ElementType.METHOD)
 public @interface PreferenceClick {

diff --git a/...idannotations-api/src/main/java/org/androidannotations/annotations/PreferenceHeaders.java b/...idannotations-api/src/main/java/org/androidannotations/annotations/PreferenceHeaders.java
@@ -20,6 +20,43 @@
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
+/**
+ * <p>
+ * Should be used on a {@link org.androidannotations.annotations.EActivity
+ * EActivity} class which is a subclass of
+ * {@link android.preference.PreferenceActivity PreferenceActivity}, to inject
+ * the preference headers from resource.
+ * </p>
+ * <p>
+ * The annotation value should be one of R.xml.* fields.
+ * </p>
+ * 
+ * <blockquote>
+ *
+ * Example :
+ *
+ * <pre>
+ * &#064;PreferenceHeaders(R.xml.preference_headers)
+ * &#064;EActivity
+ * public class SettingsActivity extends PreferenceActivity {
+ * 
+ * 	&#064;PreferenceByKey(R.string.myPref1)
+ * 	Preference myPreference1;
+ * 
+ * 	&#064;PreferenceByKey(R.string.checkBoxPref)
+ * 	CheckBoxPreference checkBoxPref;
+ * 
+ * 	&#064;AfterPreferences
+ * 	void initPrefs() {
+ * 		checkBoxPref.setChecked(false);
+ * 	}
+ * }
+ * </pre>
+ *
+ * </blockquote>
+ * 
+ * @see PreferenceScreen
+ */
 @Retention(RetentionPolicy.CLASS)
 @Target(ElementType.TYPE)
 public @interface PreferenceHeaders {

diff --git a/...oidannotations-api/src/main/java/org/androidannotations/annotations/PreferenceScreen.java b/...oidannotations-api/src/main/java/org/androidannotations/annotations/PreferenceScreen.java
@@ -20,6 +20,44 @@
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
+/**
+ * <p>
+ * Should be used on {@link org.androidannotations.annotations.EActivity
+ * EActivity} or {@link org.androidannotations.annotations.EFragment EFragment}
+ * classes which are subclass of {@link android.preference.PreferenceActivity
+ * PreferenceActivity} or <code>PreferenceFragment</code>, to inject the
+ * preference screen from resource.
+ * </p>
+ * <p>
+ * The annotation value should be one of R.xml.* fields.
+ * </p>
+ * 
+ * <blockquote>
+ *
+ * Example :
+ *
+ * <pre>
+ * &#064;PreferenceScreen(R.xml.settings)
+ * &#064;EActivity
+ * public class SettingsActivity extends PreferenceActivity {
+ * 
+ * 	&#064;PreferenceByKey(R.string.myPref1)
+ * 	Preference myPreference1;
+ * 
+ * 	&#064;PreferenceByKey(R.string.checkBoxPref)
+ * 	CheckBoxPreference checkBoxPref;
+ * 
+ * 	&#064;AfterPreferences
+ * 	void initPrefs() {
+ * 		checkBoxPref.setChecked(false);
+ * 	}
+ * }
+ * </pre>
+ *
+ * </blockquote>
+ * 
+ * @see PreferenceHeaders
+ */
 @Retention(RetentionPolicy.CLASS)
 @Target(ElementType.TYPE)
 public @interface PreferenceScreen {