Add more dartdocs (#9174)

examples/flutter_gallery/lib/demo/cupertino/cupertino_buttons_demo.dart

@@ -5,6 +5,8 @@
 import 'package:flutter/cupertino.dart';
 import 'package:flutter/material.dart';
 
+const Color _kBlue = const Color(0xFF007AFF);
+
 class CupertinoButtonsDemo extends StatefulWidget {
   static const String routeName = '/cupertino/buttons';
 
@@ -55,7 +57,7 @@ class _CupertinoButtonDemoState extends State<CupertinoButtonsDemo> {
                 new Padding(padding: const EdgeInsets.all(12.0)),
                 new CupertinoButton(
                   child: new Text('With Background'),
-                  color: CupertinoButton.kBlue,
+                  color: _kBlue,
                   onPressed: () {
                     setState(() {_pressedCount++;});
                   }
@@ -63,7 +65,7 @@ class _CupertinoButtonDemoState extends State<CupertinoButtonsDemo> {
                 new Padding(padding: const EdgeInsets.all(12.0)),
                 new CupertinoButton(
                   child: new Text('Disabled'),
-                  color: CupertinoButton.kBlue,
+                  color: _kBlue,
                   onPressed: null,
                 ),
               ],

examples/flutter_gallery/lib/demo/cupertino/cupertino_dialog_demo.dart

@@ -5,6 +5,8 @@
 import 'package:flutter/cupertino.dart';
 import 'package:flutter/material.dart';
 
+const Color _kBlue = const Color(0xFF007AFF);
+
 class CupertinoDialogDemo extends StatefulWidget {
   static const String routeName = '/cupertino/dialog';
 
@@ -30,8 +32,6 @@ class _CupertinoDialogDemoState extends State<CupertinoDialogDemo> {
     });
   }
 
-
-
   @override
   Widget build(BuildContext context) {
     return new Scaffold(
@@ -44,7 +44,7 @@ class _CupertinoDialogDemoState extends State<CupertinoDialogDemo> {
         children: <Widget> [
           new CupertinoButton(
             child: new Text('Alert'),
-            color: CupertinoButton.kBlue,
+            color: _kBlue,
             onPressed: () {
               showDemoDialog<String>(
                 context: context,
@@ -68,7 +68,7 @@ class _CupertinoDialogDemoState extends State<CupertinoDialogDemo> {
           new Padding(padding: const EdgeInsets.all(8.0)),
           new CupertinoButton(
             child: new Text('Alert with Title'),
-            color: CupertinoButton.kBlue,
+            color: _kBlue,
             padding: const EdgeInsets.symmetric(vertical: 16.0, horizontal: 36.0),
             onPressed: () {
               showDemoDialog<String>(

packages/flutter/lib/src/cupertino/button.dart

@@ -5,28 +5,34 @@
 import 'package:flutter/foundation.dart';
 import 'package:flutter/widgets.dart';
 
+// TODO(xster): move this to a common Cupertino color palette with the next yak.
+const Color _kBlue = const Color(0xFF007AFF);
+const Color _kWhite = const Color(0xFFFFFFFF);
+const Color _kDisabledBackground = const Color(0xFFA9A9A9);
+const Color _kDisabledForeground = const Color(0xFFC4C4C4);
+
 const TextStyle _kButtonTextStyle = const TextStyle(
   fontFamily: '.SF UI Text',
   inherit: false,
   fontSize: 15.0,
   fontWeight: FontWeight.normal,
-  color: CupertinoButton.kBlue,
+  color: _kBlue,
   textBaseline: TextBaseline.alphabetic,
 );
 
 final TextStyle _kDisabledButtonTextStyle = _kButtonTextStyle.copyWith(
-  color: CupertinoButton.kDisabledForeground,
+  color: _kDisabledForeground,
 );
 
 final TextStyle _kBackgroundButtonTextStyle = _kButtonTextStyle.copyWith(
-  color: CupertinoButton.kWhite,
+  color: _kWhite,
 );
 
 const EdgeInsets _kButtonPadding = const EdgeInsets.all(16.0);
 const EdgeInsets _kBackgroundButtonPadding =
     const EdgeInsets.symmetric(vertical: 16.0, horizontal: 64.0);
 
-/// An iOS style button.
+/// An iOS-style button.
 ///
 /// Takes in a text or an icon that fades out and in on touch. May optionally have a
 /// background.
@@ -35,13 +41,7 @@ const EdgeInsets _kBackgroundButtonPadding =
 ///
 ///  * <https://developer.apple.com/ios/human-interface-guidelines/ui-controls/buttons/>
 class CupertinoButton extends StatefulWidget {
-  // TODO(xster): move this to a common Cupertino color palatte with the next yak.
-  static const Color kBlue = const Color(0xFF007AFF);
-  static const Color kWhite = const Color(0xFFFFFFFF);
-  static const Color kDisabledBackground = const Color(0xFFA9A9A9);
-  static const Color kDisabledForeground = const Color(0xFFC4C4C4);
-
-
+  /// Creates an iOS-style button.
   CupertinoButton({
     @required this.child,
     this.padding,
@@ -156,7 +156,7 @@ class _CupertinoButtonState extends State<CupertinoButton> with SingleTickerProv
               decoration: new BoxDecoration(
                 borderRadius: const BorderRadius.all(const Radius.circular(8.0)),
                 backgroundColor: backgroundColor != null && !enabled
-                    ? CupertinoButton.kDisabledBackground
+                    ? _kDisabledBackground
                     : backgroundColor,
               ),
               child: new Padding(

packages/flutter/lib/src/cupertino/switch.dart

@@ -25,6 +25,7 @@ import 'thumb_painter.dart';
 ///
 ///  * <https://developer.apple.com/ios/human-interface-guidelines/ui-controls/switches/>
 class CupertinoSwitch extends StatefulWidget {
+  /// Creates an iOS-style switch.
   CupertinoSwitch({
     Key key,
     @required this.value,

packages/flutter/lib/src/cupertino/thumb_painter.dart

@@ -6,18 +6,32 @@ import 'package:flutter/painting.dart';
 
 final MaskFilter _kShadowMaskFilter = new MaskFilter.blur(BlurStyle.normal, BoxShadow.convertRadiusToSigma(1.0));
 
+/// Paints an iOS-style slider thumb.
+///
+/// Used by [CupertinoSwitch] and [CupertinoSlider].
 class CupertinoThumbPainter {
+  /// Creates an object that paints an iOS-style slider thumb.
   CupertinoThumbPainter({
     this.color: const Color(0xFFFFFFFF),
     this.shadowColor: const Color(0x2C000000),
   });
 
+  /// The color of the interior of the thumb.
   final Color color;
+
+  /// The color of the shadow case by the thumb.
   final Color shadowColor;
 
+  /// Half the default diameter of the thumb.
   static const double radius = 14.0;
+
+  /// The default amount the thumb should be extended horizontally when pressed.
   static const double extension = 7.0;
 
+  /// Paints the thumb onto the given canvas in the given rectangle.
+  ///
+  /// Consider using [radius] and [extension] when deciding how large a
+  /// rectangle to use for the thumb.
   void paint(Canvas canvas, Rect rect) {
     final RRect rrect = new RRect.fromRectAndRadius(rect, new Radius.circular(rect.shortestSide / 2.0));
 

packages/flutter/lib/src/gestures/velocity_tracker.dart

@@ -147,6 +147,7 @@ class VelocityTracker {
   final List<_PointAtTime> _samples = new List<_PointAtTime>(_kHistorySize);
   int _index = 0;
 
+  /// Adds a position as the given time to the tracker.
   void addPosition(Duration time, Point position) {
     _index += 1;
     if (_index == _kHistorySize)
@@ -154,6 +155,8 @@ class VelocityTracker {
     _samples[_index] = new _PointAtTime(position, time);
   }
 
+  /// Returns an estimate of the velocity of the object being tracked by the
+  /// tracker given the current information available to the tracker.
   VelocityEstimate getVelocityEstimate() {
     final List<double> x = <double>[];
     final List<double> y = <double>[];

packages/flutter/lib/src/material/list_tile.dart

@@ -40,10 +40,10 @@ enum MaterialListType {
 /// text style, which is a little smaller than the theme's [TextTheme.subhead]
 /// text style, which is used by default.
 enum ListTileStyle {
-  // Use a title font that's appropriate for a [ListTile] in a list.
+  /// Use a title font that's appropriate for a [ListTile] in a list.
   list,
 
-  // Use a title font that's appropriate for a [ListTile] that appears in a [Drawer].
+  /// Use a title font that's appropriate for a [ListTile] that appears in a [Drawer].
   drawer,
 }
 

packages/flutter/lib/src/material/page.dart

@@ -75,6 +75,11 @@ class MaterialPageRoute<T> extends PageRoute<T> {
 
   /// Builds the primary contents of the route.
   final WidgetBuilder builder;
+
+  /// Whether this route is a full-screen dialog.
+  ///
+  /// Prevents [startPopGesture] from poping the route using an edge swipe on
+  /// iOS.
   final bool fullscreenDialog;
 
   @override

packages/flutter/lib/src/material/text_selection.dart

@@ -196,4 +196,5 @@ class _MaterialTextSelectionControls extends TextSelectionControls {
   }
 }
 
+/// Text selection controls that follow the Material Design specification.
 final TextSelectionControls materialTextSelectionControls = new _MaterialTextSelectionControls();

packages/flutter/lib/src/widgets/editable_text.dart

@@ -23,27 +23,70 @@ export 'package:flutter/services.dart' show TextEditingValue, TextSelection, Tex
 
 const Duration _kCursorBlinkHalfPeriod = const Duration(milliseconds: 500);
 
+/// A controller for an editable text field.
+///
+/// Whenever the user modifies a text field with an associated
+/// [TextEditingController], the text field updates [value] and the controller
+/// notifies its listeners. Listeners can then read the [text] and [selection]
+/// properties to learn what the user has typed or how the selection has been
+/// updated.
+///
+/// Similarly, if you modify the [text] or [selection] properties, the text
+/// field will be notified and will update itself appropriately.
+///
+/// A [TextEditingController] can also be used to provide an initial value for a
+/// text field. If you build a text field with a controller that already has
+/// [text], the text field will use that text as its initial value.
+///
+/// See also:
+///
+///  * [TextField], which is a Material Design text field that can be controlled
+///    with a [TextEditingController].
+///  * [EditableText], which is a raw region of editable text that can be
+///    controlled with a [TextEditingController].
 class TextEditingController extends ValueNotifier<TextEditingValue> {
+  /// Creates a controller for an editable text field.
+  ///
+  /// This constructor treats a null [text] argument as if it were the empty
+  /// string.
   TextEditingController({ String text })
     : super(text == null ? TextEditingValue.empty : new TextEditingValue(text: text));
 
+  /// Creates a controller for an editiable text field from an initial [TextEditingValue].
+  ///
+  /// This constructor treats a null [value] argument as if it were
+  /// [TextEditingValue.empty].
   TextEditingController.fromValue(TextEditingValue value)
     : super(value ?? TextEditingValue.empty);
 
+  /// The current string the user is editing.
   String get text => value.text;
   set text(String newText) {
     value = value.copyWith(text: newText, composing: TextRange.empty);
   }
 
+  /// The currently selected [text].
+  ///
+  /// If the selection is collapsed, then this property gives the offset of the
+  /// cursor within the text.
   TextSelection get selection => value.selection;
   set selection(TextSelection newSelection) {
     value = value.copyWith(selection: newSelection, composing: TextRange.empty);
   }
 
+  /// Set the [value] to empty.
+  ///
+  /// After calling this function, [text] will be the empty string and the
+  /// selection will be invalid.
   void clear() {
     value = TextEditingValue.empty;
   }
 
+  /// Set the composing region to an empty range.
+  ///
+  /// The composing region is the range of text that is still being composed.
+  /// Calling this function indicates that the user is done composing that
+  /// region.
   void clearComposing() {
     value = value.copyWith(composing: TextRange.empty);
   }