Merge pull request #3035 from abarth/doc_updates

Add review feedback to dartdocs

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

@@ -23,6 +23,7 @@ import 'toggleable.dart';
 /// Requires one of its ancestors to be a [Material] widget.
 ///
 /// See also:
+///
 ///  * [Radio]
 ///  * [Switch]
 ///  * [Slider]
@@ -40,15 +41,21 @@ class Checkbox extends StatelessWidget {
     this.onChanged
   }) : super(key: key);
 
-  /// Whether this checkbox is checked or unchecked.
+  /// Whether this checkbox is checked.
   final bool value;
 
   /// The color to use when this checkbox is checked.
   ///
-  /// Defaults to accent color of the current theme.
+  /// Defaults to accent color of the current [Theme].
   final Color activeColor;
 
   /// Called when the user checks or unchecks the checkbox.
+  ///
+  /// The checkbox passes the new value to the callback but does not actually
+  /// change state until the parent widget rebuilds the checkbox with the new
+  /// value.
+  ///
+  /// If null, the checkbox will be displayed as disabled.
   final ValueChanged<bool> onChanged;
 
   @override

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

@@ -31,6 +31,7 @@ const TextStyle _kLabelStyle = const TextStyle(
 /// Requires one of its ancestors to be a [Material] widget.
 ///
 /// See also:
+///
 ///  * [CircleAvatar]
 ///  * https://www.google.com/design/spec/components/chips.html
 class Chip extends StatelessWidget {
@@ -53,7 +54,7 @@ class Chip extends StatelessWidget {
 
   /// Called when the user deletes the chip, e.g., by tapping the delete button.
   ///
-  /// The delete button is included in the ship only if this callback is non-null.
+  /// The delete button is included in the chip only if this callback is non-null.
   final VoidCallback onDeleted;
 
   @override

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

@@ -14,6 +14,7 @@ import 'theme.dart';
 /// always be paired with the same background color, for consistency.
 ///
 /// See also:
+///
 ///  * [Chip]
 ///  * [ListItem]
 ///  * <https://www.google.com/design/spec/components/chips.html#chips-contact-chips>

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

@@ -25,6 +25,7 @@ enum _DatePickerMode { day, year }
 /// Requires one of its ancestors to be a [Material] widget.
 ///
 /// See also:
+///
 ///  * [showDatePicker]
 ///  * <https://www.google.com/design/spec/components/pickers.html#pickers-date-pickers>
 class DatePicker extends StatefulWidget {
@@ -192,6 +193,7 @@ class _DatePickerHeader extends StatelessWidget {
 /// Part of the material design [DatePicker].
 ///
 /// See also:
+///
 ///  * [DatePicker].
 ///  * <https://www.google.com/design/spec/components/pickers.html#pickers-date-pickers>
 class DayPicker extends StatelessWidget {
@@ -320,6 +322,7 @@ class DayPicker extends StatelessWidget {
 /// Part of the material design [DatePicker].
 ///
 /// See also:
+///
 ///  * [DatePicker]
 ///  * <https://www.google.com/design/spec/components/pickers.html#pickers-date-pickers>
 class MonthPicker extends StatefulWidget {
@@ -432,6 +435,7 @@ class _MonthPickerState extends State<MonthPicker> {
 /// Requires one of its ancestors to be a [Material] widget.
 ///
 /// See also:
+///
 ///  * [DatePicker]
 ///  * <https://www.google.com/design/spec/components/pickers.html#pickers-date-pickers>
 class YearPicker extends StatefulWidget {

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

@@ -85,6 +85,7 @@ class _DatePickerDialogState extends State<_DatePickerDialog> {
 /// the initialDate.
 ///
 /// See also:
+///
 ///  * [DatePicker]
 ///  * [showTimePicker]
 ///  * <https://www.google.com/design/spec/components/pickers.html#pickers-date-pickers>

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

@@ -30,10 +30,13 @@ const Duration _kBaseSettleDuration = const Duration(milliseconds: 246);
 ///
 /// Typically used in the [Scaffold.drawer] property, a drawer slides in from
 /// the side of the screen and displays a list of items that the user can
-/// interact with. The top-most item in a drawer is typically a [DrawerHeader]
-/// that displays status information about the current user.
+/// interact with.
+///
+/// Typically, the child of the drawer is a [Block] whose first child is a
+/// [DrawerHeader] that displays status information about the current user.
 ///
 /// See also:
+///
 ///  * [Scaffold.drawer]
 ///  * [DrawerItem]
 ///  * [DrawerHeader]
@@ -49,6 +52,8 @@ class Drawer extends StatelessWidget {
   final int elevation;
 
   /// The widget below this widget in the tree.
+  ///
+  /// Typically a [Block].
   final Widget child;
 
   @override
@@ -69,6 +74,7 @@ class Drawer extends StatelessWidget {
 /// widgets.
 ///
 /// See also:
+///
 /// * [Drawer]
 /// * [Scaffold.drawer]
 class DrawerController extends StatefulWidget {

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

@@ -15,6 +15,7 @@ import 'theme.dart';
 /// Requires one of its ancestors to be a [Material] widget.
 ///
 /// See also:
+///
 ///  * [Drawer]
 ///  * [DrawerItem]
 ///  * <https://www.google.com/design/spec/patterns/navigation-drawer.html>

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

@@ -18,6 +18,7 @@ import 'theme.dart';
 /// Requires one of its ancestors to be a [Material] widget.
 ///
 /// See also:
+///
 ///  * [Drawer]
 ///  * [DrawerHeader]
 ///  * <https://www.google.com/design/spec/patterns/navigation-drawer.html>
@@ -37,6 +38,8 @@ class DrawerItem extends StatelessWidget {
   final Widget child;
 
   /// Called when the user taps this drawer item.
+  ///
+  /// If null, the drawer item is displayed as disabled.
   final VoidCallback onPressed;
 
   /// Whether this drawer item is currently selected.

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

@@ -252,6 +252,7 @@ class DropDownMenuItem<T> extends StatelessWidget {
 /// Requires one of its ancestors to be a [Material] widget.
 ///
 /// See also:
+///
 ///  * [RaisedButton]
 ///  * [FlatButton]
 ///  * <https://www.google.com/design/spec/components/buttons.html#buttons-dropdown-buttons>

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

@@ -29,6 +29,7 @@ import 'theme.dart';
 /// Requires one of its ancestors to be a [Material] widget.
 ///
 /// See also:
+///
 ///  * [RaisedButton]
 ///  * [DropDownButton]
 ///  * https://www.google.com/design/spec/components/buttons.html

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

@@ -31,7 +31,11 @@ const Interval _kChildSegueInterval = const Interval(0.65, 1.0);
 /// If the [onPressed] callback is not specified or null, then the button will
 /// be disabled, will not react to touch.
 ///
-/// See also: <https://www.google.com/design/spec/components/buttons-floating-action-button.html>
+/// See also:
+///
+///  * [RaisedButton]
+///  * [FlatButton]
+///  * <https://www.google.com/design/spec/components/buttons-floating-action-button.html>
 class FloatingActionButton extends StatefulWidget {
   const FloatingActionButton({
     Key key,

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

@@ -25,7 +25,11 @@ class IconData {
 ///
 /// Use with with the [Icon] class to show specific icons.
 ///
-/// See also: <https://design.google.com/icons/>
+/// See also:
+///
+///  * [Icon]
+///  * [IconButton]
+///  * <https://design.google.com/icons/>
 class Icons {
   Icons._();
 

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

@@ -18,6 +18,7 @@ export 'package:sky_services/editing/editing.mojom.dart' show KeyboardType;
 /// Requires one of its ancestors to be a [Material] widget.
 ///
 /// See also:
+///
 ///  * <https://www.google.com/design/spec/components/text-fields.html>
 class Input extends StatefulWidget {
   Input({

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

@@ -21,6 +21,7 @@ import 'theme.dart';
 /// Requires one of its ancestors to be a [Material] widget.
 ///
 /// See also:
+///
 ///  * [MaterialList]
 ///  * [CircleAvatar]
 ///  * <https://www.google.com/design/spec/components/lists.html>
@@ -61,20 +62,29 @@ class ListItem extends StatelessWidget {
   final Widget trailing;
 
   /// Whether this list item is intended to display three lines of text.
+  ///
+  /// If false, the list item is treated as having one line if the subtitle is
+  /// null and treated as having two lines if the subtitle is non-null.
   final bool isThreeLine;
 
   /// Whether this list item is part of a vertically dense list.
   final bool dense;
 
-  /// Whether this list item should be styled with the disabled color from the theme.
+  /// Whether this list item is interactive.
   ///
-  /// If true, prevents the [onTap] and [onLongPress] callbacks from being operative.
+  /// If false, this list item is styled with the disabled color from the
+  /// current [Theme] and the [onTap] and [onLongPress] callbacks are
+  /// inoperative.
   final bool enabled;
 
   /// Called when the user taps this list item.
+  ///
+  /// Inoperative if [enabled] is false.
   final GestureTapCallback onTap;
 
   /// Called when the user long-presses on this list item.
+  ///
+  /// Inoperative if [enabled] is false.
   final GestureLongPressCallback onLongPress;
 
   /// Add a one pixel border in between each item. If color isn't specified the

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

@@ -29,6 +29,7 @@ const double _kInnerRadius = 5.0;
 /// Requires one of its ancestors to be a [Material] widget.
 ///
 /// See also:
+///
 ///  * [CheckBox]
 ///  * [Slider]
 ///  * [Switch]
@@ -53,13 +54,16 @@ class Radio<T> extends StatelessWidget {
 
   /// The color to use when this radio button is selected.
   ///
-  /// Defaults to accent color of the current theme.
+  /// Defaults to accent color of the current [Theme].
   final Color activeColor;
 
   /// Called when the user selects this radio button.
   ///
-  /// For convenence, the radio button passes [value] as a parameter to this
-  /// callback.
+  /// The radio button passes [value] as a parameter to this callback. The radio
+  /// button does not actually change state until the parent widget rebuilds the
+  /// radio button with the new [groupValue].
+  ///
+  /// If null, the radio button will be displayed as disabled.
   final ValueChanged<T> onChanged;
 
   bool get _enabled => onChanged != null;

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

@@ -26,8 +26,10 @@ import 'theme.dart';
 /// Requires one of its ancestors to be a [Material] widget.
 ///
 /// See also:
+///
 ///  * [FlatButton]
 ///  * [DropDownButton]
+///  * [FloatingActionButton]
 ///  * <https://www.google.com/design/spec/components/buttons.html>
 class RaisedButton extends MaterialButton {
   RaisedButton({

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

@@ -17,7 +17,9 @@ import 'package:flutter/painting.dart';
 /// Each entry has three shadows which must be combined to obtain the defined
 /// effect for that elevation.
 ///
-/// See also: <https://www.google.com/design/spec/what-is-material/elevation-shadows.html>
+/// See also:
+///  * [Material]
+///  * <https://www.google.com/design/spec/what-is-material/elevation-shadows.html>
 const Map<int, List<BoxShadow>> elevationToShadow = _elevationToShadow; // to hide the literal from the docs
 
 const Color _kKeyUmbraOpacity = const Color(0x33000000); // alpha = 0.2

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

@@ -23,6 +23,7 @@ import 'theme.dart';
 /// Requires one of its ancestors to be a [Material] widget.
 ///
 /// See also:
+///
 ///  * [CheckBox]
 ///  * [Radio]
 ///  * [Switch]
@@ -59,10 +60,16 @@ class Slider extends StatelessWidget {
 
   /// The color to use for the portion of the slider that has been selected.
   ///
-  /// Defaults to accent color of the current theme.
+  /// Defaults to accent color of the current [Theme].
   final Color activeColor;
 
   /// Called when the user selects a new value for the slider.
+  ///
+  /// The slider passes the new value to the callback but does not actually
+  /// change state until the parent widget rebuilds the slider with the new
+  /// value.
+  ///
+  /// If null, the slider will be displayed as disabled.
   final ValueChanged<double> onChanged;
 
   void _handleChanged(double value) {

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

@@ -36,7 +36,10 @@ const Curve _snackBarFadeCurve = const Interval(0.72, 1.0, curve: Curves.fastOut
 /// Snack bar actions are always enabled. If you want to disable a snack bar
 /// action, simply don't include it in the snack bar.
 ///
-/// See also: <https://www.google.com/design/spec/components/snackbars-toasts.html>
+/// See also:
+///
+///  * [SnackBar]
+///  * <https://www.google.com/design/spec/components/snackbars-toasts.html>
 class SnackBarAction extends StatelessWidget {
   SnackBarAction({Key key, this.label, this.onPressed }) : super(key: key) {
     assert(label != null);

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

@@ -25,6 +25,7 @@ import 'toggleable.dart';
 /// Requires one of its ancestors to be a [Material] widget.
 ///
 /// See also:
+///
 ///  * [CheckBox]
 ///  * [Radio]
 ///  * [Slider]
@@ -44,7 +45,7 @@ class Switch extends StatelessWidget {
 
   /// The color to use when this switch is on.
   ///
-  /// Defaults to accent color of the current theme.
+  /// Defaults to accent color of the current [Theme].
   final Color activeColor;
 
   /// A decoration to use for the thumb of this switch when the switch is on.
@@ -62,6 +63,8 @@ class Switch extends StatelessWidget {
   /// The switch passes the new value to the callback but does not actually
   /// change state until the parent widget rebuilds the switch with the new
   /// value.
+  ///
+  /// If null, the switch will be displayed as disabled.
   final ValueChanged<bool> onChanged;
 
   @override

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

@@ -582,6 +582,7 @@ class TabBarSelectionState<T> extends State<TabBarSelection<T>> {
 /// Requires one of its ancestors to be a [Material] widget.
 ///
 /// See also:
+///
 ///  * [TabBarSelection]
 ///  * [TabBarView]
 ///  * [AppBar.tabBar]

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

@@ -98,6 +98,7 @@ enum _TimePickerMode { hour, minute }
 /// [showTimePicker], which creates a time picker dialog.
 ///
 /// See also:
+///
 ///  * [showTimePicker]
 ///  * <https://www.google.com/design/spec/components/pickers.html#pickers-time-pickers>
 class TimePicker extends StatefulWidget {

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

@@ -74,6 +74,7 @@ class _TimePickerDialogState extends State<_TimePickerDialog> {
 /// the initialTime.
 ///
 /// See also:
+///
 ///  * [TimePicker]
 ///  * [showDatePicker]
 ///  * <https://www.google.com/design/spec/components/pickers.html#pickers-time-pickers>