Improve documentation (#6694)

Based on P5's experience

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

@@ -214,6 +214,8 @@ class AppBar extends StatelessWidget {
   /// The z-coordinate at which to place this app bar.
   ///
   /// The following elevations have defined shadows: 1, 2, 3, 4, 6, 8, 9, 12, 16, 24
+  ///
+  /// Defaults to 4, the appropriate elevation for app bars.
   final int elevation;
 
   /// The color to use for the app bar's material. Typically this should be set

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

@@ -158,11 +158,15 @@ class MaterialButton extends StatefulWidget {
   /// The z-coordinate at which to place this button.
   ///
   /// The following elevations have defined shadows: 1, 2, 3, 4, 6, 8, 9, 12, 16, 24
+  ///
+  /// Defaults to 0.
   final int elevation;
 
   /// The z-coordinate at which to place this button when highlighted.
   ///
   /// The following elevations have defined shadows: 1, 2, 3, 4, 6, 8, 9, 12, 16, 24
+  ///
+  /// Defaults to 0.
   final int highlightElevation;
 
   /// The smallest horizontal extent that the button will occupy.

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

@@ -6,7 +6,7 @@ import 'package:flutter/widgets.dart';
 
 import 'material.dart';
 
-/// A material design card.
+/// A material design card. A card has slightly rounded corners and a shadow.
 ///
 /// A card is a sheet of [Material] used to represent some related information,
 /// for example an album, a geographical location, a meal, contact details, etc.
@@ -33,7 +33,11 @@ class Card extends StatelessWidget {
   /// The color of material used for this card.
   final Color color;
 
+  /// The z-coordinate at which to place this card.
+  ///
   /// The following elevations have defined shadows: 1, 2, 3, 4, 6, 8, 9, 12, 16, 24
+  ///
+  /// Defaults to 2, the appropriate elevation for cards.
   final int elevation;
 
   @override

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

@@ -61,6 +61,8 @@ class Drawer extends StatelessWidget {
   /// The z-coordinate at which to place this drawer.
   ///
   /// The following elevations have defined shadows: 1, 2, 3, 4, 6, 8, 9, 12, 16, 24
+  ///
+  /// Defaults to 16, the appropriate elevation for drawers.
   final int elevation;
 
   /// The widget below this widget in the tree.

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

@@ -336,7 +336,7 @@ class _DropdownRoute<T> extends PopupRoute<_DropdownRouteResult<T>> {
 /// The type `T` is the type of the value the entry represents. All the entries
 /// in a given menu must represent values with consistent types.
 class DropdownMenuItem<T> extends StatelessWidget {
-  /// Creates an item for a drop down menu.
+  /// Creates an item for a dropdown menu.
   ///
   /// The [child] argument is required.
   DropdownMenuItem({
@@ -407,7 +407,7 @@ class DropdownButtonHideUnderline extends InheritedWidget {
 ///  * [FlatButton]
 ///  * <https://material.google.com/components/buttons.html#buttons-dropdown-buttons>
 class DropdownButton<T> extends StatefulWidget {
-  /// Creates a drop down button.
+  /// Creates a dropdown button.
   ///
   /// The [items] must have distinct values and [value] must be among them.
   ///
@@ -438,9 +438,11 @@ class DropdownButton<T> extends StatefulWidget {
   /// The z-coordinate at which to place the menu when open.
   ///
   /// The following elevations have defined shadows: 1, 2, 3, 4, 6, 8, 9, 12, 16, 24
+  ///
+  /// Defaults to 8, the appropriate elevation for dropdown buttons.
   final int elevation;
 
-  /// The text style to use for text in the drop down button and the drop down
+  /// The text style to use for text in the dropdown button and the dropdown
   /// menu that appears when you tap the button.
   ///
   /// Defaults to the [TextTheme.subhead] value of the current

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

@@ -81,9 +81,16 @@ class FloatingActionButton extends StatefulWidget {
   /// The z-coordinate at which to place this button.
   ///
   /// The following elevations have defined shadows: 1, 2, 3, 4, 6, 8, 9, 12, 16, 24
+  ///
+  /// Defaults to 6, the appropriate elevation for floating action buttons.
   final int elevation;
 
   /// The z-coordinate at which to place this button when the user is touching the button.
+  ///
+  /// The following elevations have defined shadows: 1, 2, 3, 4, 6, 8, 9, 12, 16, 24
+  ///
+  /// Defaults to 12, the appropriate elevation for floating action buttons
+  /// while they are being touched.
   final int highlightElevation;
 
   /// Controls the size of this button.

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

@@ -9,24 +9,29 @@ import 'debug.dart';
 import 'ink_well.dart';
 import 'theme.dart';
 
-/// An item in a material design list, typically consisting of an icon and some
-/// text.
+/// A single row typically containing an icon and some text.
 ///
-/// [MaterialList] items are one to three lines of text optionally flanked by
-/// icons. Icons are defined with the [leading] and [trailing] parameters. The
-/// first line of text is not optional and is specified with [title]. The value
-/// of [subtitle] will occupy the space allocated for an aditional line of text,
-/// or two lines if [isThreeLine] is true. If [dense] is true then the overall
-/// height of this list item and the size of the [DefaultTextStyle]s that wrap
-/// the [title] and [subtitle] widget are reduced.
+/// List items are one to three lines of text optionally flanked by icons or
+/// other widgets, such as check boxes. The icons (or other widgets) for the
+/// item are defined with the [leading] and [trailing] parameters. The first
+/// line of text is not optional and is specified with [title]. The value of
+/// [subtitle], which _is_ optional, will occupy the space allocated for an
+/// additional line of text, or two lines if [isThreeLine] is true. If [dense]
+/// is true then the overall height of this list item and the size of the
+/// [DefaultTextStyle]s that wrap the [title] and [subtitle] widget are reduced.
+///
+/// List items are typically used in [MaterialList]s or in [Card]s.
 ///
 /// Requires one of its ancestors to be a [Material] widget.
 ///
 /// See also:
 ///
-///  * [MaterialList]
-///  * [CircleAvatar]
-///  * [Divider]
+///  * [MaterialList], which takes a list of [ListItem] widgets and shows them
+///    as a scrolling list.
+///  * [Card], which can be used with [Column] to show a few [ListItem]s.
+///  * [CircleAvatar], which shows an icon representing a person.
+///  * [Divider], which can be used to separate [ListItem]s.
+///  * [ListItem.divideItems], another way to separate [ListItem]s.
 ///  * <https://material.google.com/components/lists.html>
 class ListItem extends StatelessWidget {
   /// Creates a list item.

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

@@ -190,6 +190,8 @@ class Material extends StatefulWidget {
   /// The z-coordinate at which to place this material.
   ///
   /// The following elevations have defined shadows: 1, 2, 3, 4, 6, 8, 9, 12, 16, 24
+  ///
+  /// Defaults to 0.
   final int elevation;
 
   /// The color to paint the material.

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

@@ -87,6 +87,11 @@ class MaterialGap extends MergeableMaterialItem {
 ///
 /// When a new slice is added or removed, the app is responsible for animating
 /// the transition of the slices, while the gaps will be animated automatically.
+///
+/// See also:
+///
+///  * [Card], a piece of material that does not support splitting and merging
+///    but otherwise looks the same.
 class MergeableMaterial extends StatefulWidget {
   /// Creates a mergeable Material list of items.
   MergeableMaterial({
@@ -103,7 +108,11 @@ class MergeableMaterial extends StatefulWidget {
   /// The main layout axis.
   final Axis mainAxis;
 
-  /// The elevation of all the [Material] slices.
+  /// The z-coordinate at which to place all the [Material] slices.
+  ///
+  /// The following elevations have defined shadows: 1, 2, 3, 4, 6, 8, 9, 12, 16, 24
+  ///
+  /// Defaults to 2, the appropriate elevation for cards.
   final int elevation;
 
   /// Whether connected pieces of [MaterialSlice] have dividers between them.

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

@@ -424,11 +424,19 @@ class _PopupMenuRoute<T> extends PopupRoute<T> {
   }
 }
 
-/// Show a popup menu that contains the [items] at [position]. If [initialValue]
+/// Show a popup menu that contains the `items` at `position`. If `initialValue`
 /// is specified then the first item with a matching value will be highlighted
-/// and the value of [position] implies where the left, center point of the
-/// highlighted item should appear. If [initialValue] is not specified then position
-/// implies the menu's origin.
+/// and the value of `position` implies where the left, center point of the
+/// highlighted item should appear. If `initialValue` is not specified then
+/// `position` specifies the menu's origin.
+///
+/// The `context` argument is used to look up a [Navigator] to show the menu and
+/// a [Theme] to use for the menu.
+///
+/// The `elevation` argument specifies the z-coordinate at which to place the
+/// menu. The following elevations have defined shadows: 1, 2, 3, 4, 6, 8, 9,
+/// 12, 16, 24. The elevation defaults to 8, the appropriate elevation for popup
+/// menus.
 Future<dynamic/*=T*/> showMenu/*<T>*/({
   BuildContext context,
   RelativeRect position,

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

@@ -74,16 +74,23 @@ class RaisedButton extends StatelessWidget {
   /// The z-coordinate at which to place this button.
   ///
   /// The following elevations have defined shadows: 1, 2, 3, 4, 6, 8, 9, 12, 16, 24
+  ///
+  /// Defaults to 2, the appropriate elevation for raised buttons.
   final int elevation;
 
   /// The z-coordinate at which to place this button when highlighted.
   ///
   /// The following elevations have defined shadows: 1, 2, 3, 4, 6, 8, 9, 12, 16, 24
+  ///
+  /// Defaults to 8, the appropriate elevation for raised buttons while they are
+  /// being touched.
   final int highlightElevation;
 
   /// The z-coordinate at which to place this button when disabled.
   ///
   /// The following elevations have defined shadows: 1, 2, 3, 4, 6, 8, 9, 12, 16, 24
+  ///
+  /// Defaults to 0, the appropriate elevation for disabled raised buttons.
   final int disabledElevation;
 
   /// The theme brightness to use for this button.

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

@@ -27,10 +27,10 @@ import 'virtual_viewport.dart';
 ///
 /// See also:
 ///
-///  * [Block].
-///  * [ScrollableLazyList].
-///  * [LazyBlock].
-///  * [ScrollableViewport].
+///  * [Block], which allows its children to have arbitrary sizes.
+///  * [ScrollableLazyList], a more efficient version of [ScrollableList].
+///  * [LazyBlock], a more efficient version of [Block].
+///  * [ScrollableViewport], which only has one child.
 class ScrollableList extends StatelessWidget {
   /// Creats a scrollable list of children that have equal size.
   ///