From 38ed689d95808856666549755ae9191c5c501d16 Mon Sep 17 00:00:00 2001
From: Joe Fernandez <joefernandez@google.com>
Date: Tue, 25 Apr 2017 22:06:48 -0700
Subject: [PATCH] docs: Update EditText JavaDoc comments

rework the edit text introduction and overview.

- adds an example of a basic configuration
- discuss the inputType attribute
- cross link to relevant classes & methods
- Rework the edit text introduction and overview
- wrap guide link in a p to emphasize
- emphasize specifying the inputType is required

Test: docs only change. Verified with doc test build
Change-Id: I78d8c861c51117bfd61e8c37ad83854a2aeec967
---
 core/java/android/widget/EditText.java | 32 ++++++++++++++++++++++----
 1 file changed, 28 insertions(+), 4 deletions(-)

diff --git a/core/java/android/widget/EditText.java b/core/java/android/widget/EditText.java
index 07ad872bd8f03..56c3e4a5ee776 100644
--- a/core/java/android/widget/EditText.java
+++ b/core/java/android/widget/EditText.java
@@ -33,11 +33,35 @@ import android.view.accessibility.AccessibilityNodeInfo;
  */
 
 /**
- * EditText is a thin veneer over TextView that configures itself
- * to be editable.
+ * A user interface element for entering and modifying text.
+ * When you define an edit text widget, you must specify the
+ * {@link android.R.styleable#TextView_inputType}
+ * attribute. For example, for plain text input set inputType to "text":
+ * <p>
+ * <pre>
+ * &lt;EditText
+ *     android:id="@+id/plain_text_input"
+ *     android:layout_height="wrap_content"
+ *     android:layout_width="match_parent"
+ *     android:inputType="text"/&gt;</pre>
  *
- * <p>See the <a href="{@docRoot}guide/topics/ui/controls/text.html">Text Fields</a>
- * guide.</p>
+ * Choosing the input type configures the keyboard type that is shown, acceptable characters,
+ * and appearance of the edit text.
+ * For example, if you want to accept a secret number, like a unique pin or serial number,
+ * you can set inputType to "numericPassword".
+ * An inputType of "numericPassword" results in an edit text that accepts numbers only,
+ * shows a numeric keyboard when focused, and masks the text that is entered for privacy.
+ * <p>
+ * See the <a href="{@docRoot}guide/topics/ui/controls/text.html">Text Fields</a>
+ * guide for examples of other
+ * {@link android.R.styleable#TextView_inputType} settings.
+ * </p>
+ * <p>You also can receive callbacks as a user changes text by
+ * adding a {@link android.text.TextWatcher} to the edit text.
+ * This is useful when you want to add auto-save functionality as changes are made,
+ * or validate the format of user input, for example.
+ * You add a text watcher using the {@link TextView#addTextChangedListener} method.
+ * </p>
  * <p>
  * This widget does not support auto-sizing text.
  * <p>