Add missing docs (#9696)

packages/flutter/lib/src/services/text_formatter.dart

@@ -4,23 +4,23 @@
 
 import 'package:flutter/services.dart';
 
-/// A [TextInputFormatter] can be optionally injected into an [EditableText] 
+/// A [TextInputFormatter] can be optionally injected into an [EditableText]
 /// to provide as-you-type validation and formatting of the text being edited.
-/// 
+///
 /// Text modification should only be applied when text is being committed by the
-/// IME and not on text under composition (i.e. when 
-/// [TextEditingValue.composing] is collapsed). 
-/// 
-/// Concrete implementations [BlacklistingTextInputFormatter], which removes 
-/// blacklisted characters upon edit commit, and 
+/// IME and not on text under composition (i.e., only when
+/// [TextEditingValue.composing] is collapsed).
+///
+/// Concrete implementations [BlacklistingTextInputFormatter], which removes
+/// blacklisted characters upon edit commit, and
 /// [WhitelistingTextInputFormatter], which only allows entries of whitelisted
-/// characters, are provided. 
-/// 
-/// To create custom formatters, extend the [TextInputFormatter] class and 
+/// characters, are provided.
+///
+/// To create custom formatters, extend the [TextInputFormatter] class and
 /// implement the [formatEditUpdate] method.
-/// 
+///
 /// See also:
-///  
+///
 ///  * [EditableText] on which the formatting apply.
 ///  * [BlacklistingTextInputFormatter], a provided formatter for blacklisting
 ///    characters.
@@ -28,14 +28,14 @@ import 'package:flutter/services.dart';
 ///    characters.
 abstract class TextInputFormatter {
   /// Called when text is being typed or cut/copy/pasted in the [EditableText].
-  /// 
+  ///
   /// You can override the resulting text based on the previous text value and
   /// the incoming new text value.
-  /// 
+  ///
   /// When formatters are chained, `oldValue` reflects the initial value of
   /// [TextEditingValue] at the beginning of the chain.
   TextEditingValue formatEditUpdate(
-    TextEditingValue oldValue, 
+    TextEditingValue oldValue,
     TextEditingValue newValue
   );
 
@@ -48,50 +48,52 @@ abstract class TextInputFormatter {
   }
 }
 
-/// Function signature expected for creating custom [TextInputFormatter] 
+/// Function signature expected for creating custom [TextInputFormatter]
 /// shorthands via [TextInputFormatter.withFunction];
 typedef TextEditingValue TextInputFormatFunction(
-    TextEditingValue oldValue, 
+    TextEditingValue oldValue,
     TextEditingValue newValue,
 );
 
 /// Wiring for [TextInputFormatter.withFunction].
 class _SimpleTextInputFormatter extends TextInputFormatter {
-  _SimpleTextInputFormatter(this.formatFunction) : 
+  _SimpleTextInputFormatter(this.formatFunction) :
     assert(formatFunction != null);
 
   final TextInputFormatFunction formatFunction;
-  
+
   @override
   TextEditingValue formatEditUpdate(
-    TextEditingValue oldValue, 
+    TextEditingValue oldValue,
     TextEditingValue newValue
   ) {
     return formatFunction(oldValue, newValue);
   }
 }
 
-/// A [TextInputFormatter] that prevents the insertion of blacklisted 
+/// A [TextInputFormatter] that prevents the insertion of blacklisted
 /// characters patterns.
-/// 
-/// Instances of blacklisted characters found in the new [TextEditingValue]s 
-/// will be replaced with the [replacementString] which defaults to ``.
-/// 
+///
+/// Instances of blacklisted characters found in the new [TextEditingValue]s
+/// will be replaced with the [replacementString] which defaults to the empty
+/// string.
+///
 /// Since this formatter only removes characters from the text, it attempts to
 /// preserve the existing [TextEditingValue.selection] to values it would now
 /// fall at with the removed characters.
-/// 
+///
 /// See also:
-///  
-///  * [TextInputFormatter].
-///  * [WhitelistingTextInputFormatter].
+///
+///  * [WhitelistingTextInputFormatter], which uses a whitelist instead of a
+///    blacklist.
 class BlacklistingTextInputFormatter extends TextInputFormatter {
+  /// Creates a formatter that prevents the insertion of blacklisted characters patterns.
+  ///
+  /// The [blacklistedPattern] must not be null.
   BlacklistingTextInputFormatter(
-    this.blacklistedPattern, 
-    {
-      this.replacementString: '',
-    }
-  ) : assert(blacklistedPattern != null);
+    this.blacklistedPattern, {
+    this.replacementString: '',
+  }) : assert(blacklistedPattern != null);
 
   /// A [Pattern] to match and replace incoming [TextEditingValue]s.
   final Pattern blacklistedPattern;
@@ -105,7 +107,7 @@ class BlacklistingTextInputFormatter extends TextInputFormatter {
     TextEditingValue newValue,
   ) {
     return _selectionAwareTextManipulation(
-      newValue, 
+      newValue,
       (String substring) {
         return substring.replaceAll(blacklistedPattern, replacementString);
       },
@@ -117,23 +119,26 @@ class BlacklistingTextInputFormatter extends TextInputFormatter {
       = new BlacklistingTextInputFormatter(new RegExp(r'\n'));
 }
 
-/// A [TextInputFormatter] that allows only the insertion of whitelisted 
+/// A [TextInputFormatter] that allows only the insertion of whitelisted
 /// characters patterns.
-/// 
+///
 /// Since this formatter only removes characters from the text, it attempts to
 /// preserve the existing [TextEditingValue.selection] to values it would now
 /// fall at with the removed characters.
-/// 
+///
 /// See also:
-///  
-///  * [TextInputFormatter].
-///  * [BlacklistingTextInputFormatter].
+///
+///  * [BlacklistingTextInputFormatter], which uses a blacklist instead of a
+///    whitelist.
 class WhitelistingTextInputFormatter extends TextInputFormatter {
-  WhitelistingTextInputFormatter(this.whitelistedPattern) : 
+  /// Creates a formatter that allows only the insertion of whitelisted characters patterns.
+  ///
+  /// The [blacklistedPattern] must not be null.
+  WhitelistingTextInputFormatter(this.whitelistedPattern) :
     assert(whitelistedPattern != null);
 
   /// A [Pattern] to extract all instances of allowed characters.
-  /// 
+  ///
   /// [RegExp] with multiple groups is not supported.
   final Pattern whitelistedPattern;
 
@@ -143,7 +148,7 @@ class WhitelistingTextInputFormatter extends TextInputFormatter {
     TextEditingValue newValue,
   ) {
     return _selectionAwareTextManipulation(
-      newValue, 
+      newValue,
       (String substring) {
         return whitelistedPattern
             .allMatches(substring)
@@ -186,8 +191,8 @@ TextEditingValue _selectionAwareTextManipulation(
   }
   return new TextEditingValue(
     text: manipulatedText,
-    selection: manipulatedSelection ?? const TextSelection.collapsed(offset: -1), 
-    composing: manipulatedText == value.text 
+    selection: manipulatedSelection ?? const TextSelection.collapsed(offset: -1),
+    composing: manipulatedText == value.text
         ? value.composing
         : TextRange.empty,
   );