The documenting will continue... (#6613)

...until people understand them.

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

@@ -13,8 +13,8 @@ import 'material.dart';
 ///
 /// See also:
 ///
-///  * [Dialog]
-///  * [showDialog]
+///  * [ListItem], to display icons and text in a card.
+///  * [Dialog] and [showDialog], to display a modal card.
 ///  * <https://material.google.com/components/cards.html>
 class Card extends StatelessWidget {
   /// Creates a material design card.

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

@@ -6,19 +6,22 @@ import 'package:flutter/widgets.dart';
 
 import 'theme.dart';
 
-/// A material design divider.
-///
 /// A one logical pixel thick horizontal line, with padding on either
-/// side. The box's total height is controlled by [height].
+/// side.
+///
+/// In the material design language, this represents a divider.
 ///
 /// Dividers can be used in lists and [Drawer]s to separate content vertically.
 /// To create a one-pixel divider between items in a list, consider using
 /// [ListItem.divideItems], which is optimized for this case.
 ///
+/// The box's total height is controlled by [height]. The appropriate padding is
+/// automatically computed from the height.
+///
 /// See also:
 ///
-///  * [ListItem.divideItems]
-///  * [PopupMenuDivider]
+///  * [PopupMenuDivider], which is the equivalent but for popup menus.
+///  * [ListItem.divideItems], another approach to dividing widgets in a list.
 ///  * <https://material.google.com/components/dividers.html>
 class Divider extends StatelessWidget {
   /// Creates a material design divider.

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

@@ -9,7 +9,8 @@ import 'debug.dart';
 import 'ink_well.dart';
 import 'theme.dart';
 
-/// An item in a material design list.
+/// An item in a material design list, typically consisting of 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
@@ -93,7 +94,11 @@ class ListItem extends StatelessWidget {
   final GestureLongPressCallback onLongPress;
 
   /// Add a one pixel border in between each item. If color isn't specified the
-  /// dividerColor of the context's theme is used.
+  /// [ThemeData.dividerColor] of the context's [Theme] is used.
+  ///
+  /// See also:
+  ///
+  /// * [Divider], which you can use to obtain this effect manually.
   static Iterable<Widget> divideItems({ BuildContext context, Iterable<Widget> items, Color color }) sync* {
     assert(items != null);
     assert(color != null || context != null);
@@ -103,14 +108,14 @@ class ListItem extends StatelessWidget {
     final bool isNotEmpty = iterator.moveNext();
 
     Widget item = iterator.current;
-    while(iterator.moveNext()) {
+    while (iterator.moveNext()) {
       yield new DecoratedBox(
         decoration: new BoxDecoration(
           border: new Border(
-            bottom: new BorderSide(color: dividerColor)
-          )
+            bottom: new BorderSide(color: dividerColor),
+          ),
         ),
-        child: item
+        child: item,
       );
       item = iterator.current;
     }

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

@@ -324,6 +324,20 @@ class Scaffold extends StatefulWidget {
   /// Displayed below the app bar and behind the [floatingActionButton] and
   /// [drawer]. To avoid the body being resized to avoid the window padding
   /// (e.g., from the onscreen keyboard), see [resizeToAvoidBottomPadding].
+  ///
+  /// The widget in the body of the scaffold will be forced to the size of the
+  /// available space, to cover the entire scaffold other than any app bars,
+  /// footer buttons, or navigation bars.
+  ///
+  /// To center this widget instead, consider putting it in a [Center] widget
+  /// and having that be the body.
+  ///
+  /// If you have a column of widgets that should normally fit on the screen,
+  /// but may overflow and would in such cases need to scroll, consider using a
+  /// [Block] as the body of the scaffold.
+  ///
+  /// If you have a list of items, consider using a [LazyBlock] or
+  /// [LazyScrollableList] as the body of the scaffold.
   final Widget body;
 
   /// A button displayed on top of the body.
@@ -885,7 +899,7 @@ class ScaffoldState extends State<Scaffold> with TickerProviderStateMixin {
     if (config.appBarBehavior != AppBarBehavior.anchor) {
       body = new NotificationListener<ScrollNotification>(
         onNotification: _handleScrollNotification,
-        child: config.body
+        child: config.body,
       );
     } else {
       body = config.body;

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

@@ -1041,7 +1041,7 @@ class ScrollableViewport extends StatelessWidget {
   }
 }
 
-/// A mashup of [ScrollableViewport] and [BlockBody].
+/// A scrolling list of variably-sized children.
 ///
 /// Useful when you have a small, fixed number of children that you wish to
 /// arrange in a block layout and that might exceed the height of its container
@@ -1052,7 +1052,8 @@ class ScrollableViewport extends StatelessWidget {
 /// or [ScrollableList] (if the children all have the same fixed height), as
 /// they avoid doing work for children that are not visible.
 ///
-/// If you have a single child, then use [ScrollableViewport] directly.
+/// This widget is implemented using [ScrollableViewport] and [BlockBody]. If
+/// you have a single child, consider using [ScrollableViewport] directly.
 ///
 /// See also:
 ///