Comment clean up for InputMethodSubtype.
Change-Id: I50bca715f4caa669cb341b36a3d46358e1ad1ded
diff --git a/core/java/android/view/inputmethod/InputMethodSubtype.java b/core/java/android/view/inputmethod/InputMethodSubtype.java
index 93caabe..18dec52 100644
--- a/core/java/android/view/inputmethod/InputMethodSubtype.java
+++ b/core/java/android/view/inputmethod/InputMethodSubtype.java
@@ -31,17 +31,15 @@
import java.util.Locale;
/**
- * This class is used to specify meta information of a subtype contained in an input method.
- * Subtype can describe locale (e.g. en_US, fr_FR...) and mode (e.g. voice, keyboard...), and is
- * used for IME switch and settings. The input method subtype allows the system to bring up the
- * specified subtype of the designated input method directly.
+ * This class is used to specify meta information of a subtype contained in an input method editor
+ * (IME). Subtype can describe locale (e.g. en_US, fr_FR...) and mode (e.g. voice, keyboard...),
+ * and is used for IME switch and settings. The input method subtype allows the system to bring up
+ * the specified subtype of the designated IME directly.
*
- * <p>It should be defined in an XML resource file of the input method
- * with the <code><subtype></code> element.
- * For more information, see the guide to
+ * <p>It should be defined in an XML resource file of the input method with the
+ * <code><subtype></code> element. For more information, see the guide to
* <a href="{@docRoot}resources/articles/creating-input-method.html">
* Creating an Input Method</a>.</p>
- *
*/
public final class InputMethodSubtype implements Parcelable {
private static final String TAG = InputMethodSubtype.class.getSimpleName();
@@ -59,13 +57,24 @@
private HashMap<String, String> mExtraValueHashMapCache;
/**
- * Constructor
- * @param nameId The name of the subtype
- * @param iconId The icon of the subtype
+ * Constructor.
+ * @param nameId Resource ID of the subtype name string. The string resource may have exactly
+ * one %s in it. If there is, the %s part will be replaced with the locale's display name by
+ * the formatter. Please refer to {@link #getDisplayName} for details.
+ * @param iconId Resource ID of the subtype icon drawable.
* @param locale The locale supported by the subtype
* @param mode The mode supported by the subtype
- * @param extraValue The extra value of the subtype
- * @param isAuxiliary true when this subtype is one shot subtype.
+ * @param extraValue The extra value of the subtype. This string is free-form, but the API
+ * supplies tools to deal with a key-value comma-separated list; see
+ * {@link #containsExtraValueKey} and {@link #getExtraValueOf}.
+ * @param isAuxiliary true when this subtype is auxiliary, false otherwise. An auxiliary
+ * subtype will not be shown in the list of enabled IMEs for choosing the current IME in
+ * the Settings even when this subtype is enabled. Please note that this subtype will still
+ * be shown in the list of IMEs in the IME switcher to allow the user to tentatively switch
+ * to this subtype while an IME is shown. The framework will never switch the current IME to
+ * this subtype by {@link android.view.inputmethod.InputMethodManager#switchToLastInputMethod}.
+ * The intent of having this flag is to allow for IMEs that are invoked in a one-shot way as
+ * auxiliary input mode, and return to the previous IME once it is finished (e.g. voice input).
* @hide
*/
public InputMethodSubtype(int nameId, int iconId, String locale, String mode, String extraValue,
@@ -74,16 +83,28 @@
}
/**
- * Constructor
- * @param nameId The name of the subtype
- * @param iconId The icon of the subtype
+ * Constructor.
+ * @param nameId Resource ID of the subtype name string. The string resource may have exactly
+ * one %s in it. If there is, the %s part will be replaced with the locale's display name by
+ * the formatter. Please refer to {@link #getDisplayName} for details.
+ * @param iconId Resource ID of the subtype icon drawable.
* @param locale The locale supported by the subtype
* @param mode The mode supported by the subtype
- * @param extraValue The extra value of the subtype
- * @param isAuxiliary true when this subtype is one shot subtype.
- * @param overridesImplicitlyEnabledSubtype true when this subtype should be selected by default
- * if no other subtypes are selected explicitly. Note that a subtype with this parameter being
- * true will not be shown in the subtypes list.
+ * @param extraValue The extra value of the subtype. This string is free-form, but the API
+ * supplies tools to deal with a key-value comma-separated list; see
+ * {@link #containsExtraValueKey} and {@link #getExtraValueOf}.
+ * @param isAuxiliary true when this subtype is auxiliary, false otherwise. An auxiliary
+ * subtype will not be shown in the list of enabled IMEs for choosing the current IME in
+ * the Settings even when this subtype is enabled. Please note that this subtype will still
+ * be shown in the list of IMEs in the IME switcher to allow the user to tentatively switch
+ * to this subtype while an IME is shown. The framework will never switch the current IME to
+ * this subtype by {@link android.view.inputmethod.InputMethodManager#switchToLastInputMethod}.
+ * The intent of having this flag is to allow for IMEs that are invoked in a one-shot way as
+ * auxiliary input mode, and return to the previous IME once it is finished (e.g. voice input).
+ * @param overridesImplicitlyEnabledSubtype true when this subtype should be enabled by default
+ * if no other subtypes in the IME are enabled explicitly. Note that a subtype with this
+ * parameter being true will not be shown in the list of subtypes in each IME's subtype enabler.
+ * Having an "automatic" subtype is an example use of this flag.
*/
public InputMethodSubtype(int nameId, int iconId, String locale, String mode, String extraValue,
boolean isAuxiliary, boolean overridesImplicitlyEnabledSubtype) {
@@ -115,52 +136,60 @@
}
/**
- * @return the name of the subtype
+ * @return Resource ID of the subtype name string.
*/
public int getNameResId() {
return mSubtypeNameResId;
}
/**
- * @return the icon of the subtype
+ * @return Resource ID of the subtype icon drawable.
*/
public int getIconResId() {
return mSubtypeIconResId;
}
/**
- * @return the locale of the subtype
+ * @return The locale of the subtype. This method returns the "locale" string parameter passed
+ * to the constructor.
*/
public String getLocale() {
return mSubtypeLocale;
}
/**
- * @return the mode of the subtype
+ * @return The mode of the subtype.
*/
public String getMode() {
return mSubtypeMode;
}
/**
- * @return the extra value of the subtype
+ * @return The extra value of the subtype.
*/
public String getExtraValue() {
return mSubtypeExtraValue;
}
/**
- * @return true if this subtype is one shot subtype. One shot subtype will not be shown in the
- * ime switch list when this subtype is implicitly enabled. The framework will never
- * switch the current ime to this subtype by switchToLastInputMethod in InputMethodManager.
+ * @return true if this subtype is auxiliary, false otherwise. An auxiliary subtype will not be
+ * shown in the list of enabled IMEs for choosing the current IME in the Settings even when this
+ * subtype is enabled. Please note that this subtype will still be shown in the list of IMEs in
+ * the IME switcher to allow the user to tentatively switch to this subtype while an IME is
+ * shown. The framework will never switch the current IME to this subtype by
+ * {@link android.view.inputmethod.InputMethodManager#switchToLastInputMethod}.
+ * The intent of having this flag is to allow for IMEs that are invoked in a one-shot way as
+ * auxiliary input mode, and return to the previous IME once it is finished (e.g. voice input).
*/
public boolean isAuxiliary() {
return mIsAuxiliary;
}
/**
- * @return true when this subtype is selected by default if no other subtypes are selected
- * explicitly. Note that a subtype that returns true will not be shown in the subtypes list.
+ * @return true when this subtype will be enabled by default if no other subtypes in the IME
+ * are enabled explicitly, false otherwise. Note that a subtype with this method returning true
+ * will not be shown in the list of subtypes in each IME's subtype enabler. Having an
+ * "automatic" subtype is an example use of this flag.
*/
public boolean overridesImplicitlyEnabledSubtype() {
return mOverridesImplicitlyEnabledSubtype;
@@ -171,10 +200,10 @@
* @param packageName The package name of the IME
* @param appInfo The application info of the IME
* @return a display name for this subtype. The string resource of the label (mSubtypeNameResId)
- * can have only one %s in it. If there is, the %s part will be replaced with the locale's
- * display name by the formatter. If there is not, this method simply returns the string
- * specified by mSubtypeNameResId. If mSubtypeNameResId is not specified (== 0), it's up to the
- * framework to generate an appropriate display name.
+ * may have exactly one %s in it. If there is, the %s part will be replaced with the locale's
+ * display name by the formatter. If there is not, this method returns the string specified by
+ * mSubtypeNameResId. If mSubtypeNameResId is not specified (== 0), it's up to the framework to
+ * generate an appropriate display name.
*/
public CharSequence getDisplayName(
Context context, String packageName, ApplicationInfo appInfo) {
@@ -215,8 +244,8 @@
/**
* The string of ExtraValue in subtype should be defined as follows:
* example: key0,key1=value1,key2,key3,key4=value4
- * @param key the key of extra value
- * @return the subtype contains specified the extra value
+ * @param key The key of extra value
+ * @return The subtype contains specified the extra value
*/
public boolean containsExtraValueKey(String key) {
return getExtraValueHashMap().containsKey(key);
@@ -225,8 +254,8 @@
/**
* The string of ExtraValue in subtype should be defined as follows:
* example: key0,key1=value1,key2,key3,key4=value4
- * @param key the key of extra value
- * @return the value of the specified key
+ * @param key The key of extra value
+ * @return The value of the specified key
*/
public String getExtraValueOf(String key) {
return getExtraValueHashMap().get(key);