Improve documentation for InputType and EditorInfo.

Bug: 11245912
Change-Id: Ie92ba20079461f7f0e30d969ba3692fec3a3b97f

1 files changed, 59 insertions, 21 deletions

diff --git a/core/java/android/text/InputType.java b/core/java/android/text/InputType.java
index 6d066d6..2e3ec52 100644
--- a/core/java/android/text/InputType.java
+++ b/core/java/android/text/InputType.java
@@ -46,9 +46,9 @@ public interface InputType {
      * of text being given.  Currently supported classes are:
      * {@link #TYPE_CLASS_TEXT}, {@link #TYPE_CLASS_NUMBER},
      * {@link #TYPE_CLASS_PHONE}, {@link #TYPE_CLASS_DATETIME}.
-     * If the class is not one you
+     * <p>IME authors: If the class is not one you
      * understand, assume {@link #TYPE_CLASS_TEXT} with NO variation
-     * or flags.
+     * or flags.<p>
      */
     public static final int TYPE_MASK_CLASS = 0x0000000f;
     
@@ -69,7 +69,10 @@ public interface InputType {
      * This should be interpreted to mean that the target input connection
      * is not rich, it can not process and show things like candidate text nor
      * retrieve the current text, so the input method will need to run in a
-     * limited "generate key events" mode.
+     * limited "generate key events" mode, if it supports it. Note that some
+     * input methods may not support it, for example a voice-based input
+     * method will likely not be able to generate key events even if this
+     * flag is set.
      */
     public static final int TYPE_NULL = 0x00000000;
     
@@ -94,48 +97,70 @@ public interface InputType {
      * Flag for {@link #TYPE_CLASS_TEXT}: capitalize all characters.  Overrides
      * {@link #TYPE_TEXT_FLAG_CAP_WORDS} and
      * {@link #TYPE_TEXT_FLAG_CAP_SENTENCES}.  This value is explicitly defined
-     * to be the same as {@link TextUtils#CAP_MODE_CHARACTERS}.
+     * to be the same as {@link TextUtils#CAP_MODE_CHARACTERS}. Of course,
+     * this only affects languages where there are upper-case and lower-case letters.
      */
     public static final int TYPE_TEXT_FLAG_CAP_CHARACTERS = 0x00001000;
     
     /**
-     * Flag for {@link #TYPE_CLASS_TEXT}: capitalize first character of
-     * all words.  Overrides {@link #TYPE_TEXT_FLAG_CAP_SENTENCES}.  This
+     * Flag for {@link #TYPE_CLASS_TEXT}: capitalize the first character of
+     * every word.  Overrides {@link #TYPE_TEXT_FLAG_CAP_SENTENCES}.  This
      * value is explicitly defined
-     * to be the same as {@link TextUtils#CAP_MODE_WORDS}.
+     * to be the same as {@link TextUtils#CAP_MODE_WORDS}. Of course,
+     * this only affects languages where there are upper-case and lower-case letters.
      */
     public static final int TYPE_TEXT_FLAG_CAP_WORDS = 0x00002000;
     
     /**
-     * Flag for {@link #TYPE_CLASS_TEXT}: capitalize first character of
+     * Flag for {@link #TYPE_CLASS_TEXT}: capitalize the first character of
      * each sentence.  This value is explicitly defined
-     * to be the same as {@link TextUtils#CAP_MODE_SENTENCES}.
+     * to be the same as {@link TextUtils#CAP_MODE_SENTENCES}. For example
+     * in English it means to capitalize after a period and a space (note that other
+     * languages may have different characters for period, or not use spaces,
+     * or use different grammatical rules). Of course,
+     * this only affects languages where there are upper-case and lower-case letters.
      */
     public static final int TYPE_TEXT_FLAG_CAP_SENTENCES = 0x00004000;
     
     /**
      * Flag for {@link #TYPE_CLASS_TEXT}: the user is entering free-form
-     * text that should have auto-correction applied to it.
+     * text that should have auto-correction applied to it. Without this flag,
+     * the IME will not try to correct typos. You should always set this flag
+     * unless you really expect users to type non-words in this field, for
+     * example to choose a name for a character in a game.
+     * Contrast this with {@link TYPE_TEXT_FLAG_AUTO_COMPLETE} and
+     * {@link TYPE_TEXT_FLAG_NO_SUGGESTIONS}:
+     * {@code TYPE_TEXT_FLAG_AUTO_CORRECT} means that the IME will try to
+     * auto-correct typos as the user is typing, but does not define whether
+     * the IME offers an interface to show suggestions.
      */
     public static final int TYPE_TEXT_FLAG_AUTO_CORRECT = 0x00008000;
     
     /**
-     * Flag for {@link #TYPE_CLASS_TEXT}: the text editor is performing
-     * auto-completion of the text being entered based on its own semantics,
-     * which it will present to the user as they type.  This generally means
-     * that the input method should not be showing candidates itself, but can
-     * expect for the editor to supply its own completions/candidates from
+     * Flag for {@link #TYPE_CLASS_TEXT}: the text editor (which means
+     * the application) is performing auto-completion of the text being entered
+     * based on its own semantics, which it will present to the user as they type.
+     * This generally means that the input method should not be showing
+     * candidates itself, but can expect the editor to supply its own
+     * completions/candidates from
      * {@link android.view.inputmethod.InputMethodSession#displayCompletions
      * InputMethodSession.displayCompletions()} as a result of the editor calling
      * {@link android.view.inputmethod.InputMethodManager#displayCompletions
      * InputMethodManager.displayCompletions()}.
+     * Note the contrast with {@link TYPE_TEXT_FLAG_AUTO_CORRECT} and
+     * {@link TYPE_TEXT_FLAG_NO_SUGGESTIONS}:
+     * {@link TYPE_TEXT_FLAG_AUTO_COMPLETE} means the editor should show an
+     * interface for displaying suggestions, but instead of supplying its own
+     * it will rely on the Editor to pass completions/corrections.
      */
     public static final int TYPE_TEXT_FLAG_AUTO_COMPLETE = 0x00010000;
     
     /**
      * Flag for {@link #TYPE_CLASS_TEXT}: multiple lines of text can be
      * entered into the field.  If this flag is not set, the text field 
-     * will be constrained to a single line.
+     * will be constrained to a single line. The IME may also choose not to
+     * display an enter key when this flag is not set, as there should be no
+     * need to create new lines.
      */
     public static final int TYPE_TEXT_FLAG_MULTI_LINE = 0x00020000;
     
@@ -152,6 +177,16 @@ public interface InputType {
      * do not contain words from the language and do not benefit from any
      * dictionary-based completions or corrections. It overrides the
      * {@link #TYPE_TEXT_FLAG_AUTO_CORRECT} value when set.
+     * Please avoid using this unless you are certain this is what you want.
+     * Many input methods need suggestions to work well, for example the ones
+     * based on gesture typing. Consider clearing
+     * {@link TYPE_TEXT_FLAG_AUTO_CORRECT} instead if you just do not
+     * want the IME to correct typos.
+     * Note the contrast with {@link TYPE_TEXT_FLAG_AUTO_CORRECT} and
+     * {@link TYPE_TEXT_FLAG_AUTO_COMPLETE}:
+     * {@code TYPE_TEXT_FLAG_NO_SUGGESTIONS} means the IME should never
+     * show an interface to display suggestions. Most IMEs will also take this to
+     * mean they should not try to auto-correct what the user is typing.
      */
     public static final int TYPE_TEXT_FLAG_NO_SUGGESTIONS = 0x00080000;
 
@@ -224,7 +259,9 @@ public interface InputType {
     
     /**
      * Variation of {@link #TYPE_CLASS_TEXT}: entering text for phonetic
-     * pronunciation, such as a phonetic name field in contacts.
+     * pronunciation, such as a phonetic name field in contacts. This is mostly
+     * useful for languages where one spelling may have several phonetic
+     * readings, like Japanese.
      */
     public static final int TYPE_TEXT_VARIATION_PHONETIC = 0x000000c0;
     
@@ -255,12 +292,13 @@ public interface InputType {
     // ----------------------------------------------------------------------
     
     /**
-     * Class for numeric text.  This class supports the following flag:
+     * Class for numeric text.  This class supports the following flags:
      * {@link #TYPE_NUMBER_FLAG_SIGNED} and
      * {@link #TYPE_NUMBER_FLAG_DECIMAL}.  It also supports the following
      * variations: {@link #TYPE_NUMBER_VARIATION_NORMAL} and
-     * {@link #TYPE_NUMBER_VARIATION_PASSWORD}.  If you do not recognize
-     * the variation, normal should be assumed.
+     * {@link #TYPE_NUMBER_VARIATION_PASSWORD}.
+     * <p>IME authors: If you do not recognize
+     * the variation, normal should be assumed.</p>
      */
     public static final int TYPE_CLASS_NUMBER = 0x00000002;
     
@@ -318,7 +356,7 @@ public interface InputType {
      * following variations:
      * {@link #TYPE_DATETIME_VARIATION_NORMAL}
      * {@link #TYPE_DATETIME_VARIATION_DATE}, and
-     * {@link #TYPE_DATETIME_VARIATION_TIME},.
+     * {@link #TYPE_DATETIME_VARIATION_TIME}.
      */
     public static final int TYPE_CLASS_DATETIME = 0x00000004;