Improve Table's docs and asserts. (#6471)

packages/flutter/lib/src/rendering/table.dart

@@ -24,6 +24,14 @@ class TableCellParentData extends BoxParentData {
 }
 
 /// Base class to describe how wide a column in a [RenderTable] should be.
+///
+/// To size a column to a specific number of pixels, use a [FixedColumnWidth].
+/// This is the cheapest way to size a column.
+///
+/// Other algorithms that are relatively cheap include [FlexColumnWidth], which
+/// distributes the space equally among the flexible columns,
+/// [FractionColumnWidth], which sizes a column based on the size of the
+/// table's container.
 abstract class TableColumnWidth {
   /// Abstract const constructor. This constructor enables subclasses to provide
   /// const constructors so that they can be used in const expressions.
@@ -164,7 +172,7 @@ class FractionColumnWidth extends TableColumnWidth {
 /// Sizes the column by taking a part of the remaining space once all
 /// the other columns have been laid out.
 ///
-/// For example, if two columns have FlexColumnWidth(), then half the
+/// For example, if two columns have a [FlexColumnWidth], then half the
 /// space will go to one and half the space will go to the other.
 ///
 /// This is a cheap way to size a column.

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

@@ -23,6 +23,11 @@ export 'package:flutter/rendering.dart' show
     TableColumnWidth;
 
 /// A horizontal group of cells in a [Table].
+///
+/// Every row in a table must have the same number of children.
+///
+/// The alignment of individual cells in a row can be controlled using a
+/// [TableCell].
 class TableRow {
   /// Creates a row in a [Table].
   const TableRow({ this.key, this.decoration, this.children });
@@ -72,7 +77,13 @@ class _TableElementRow {
 
 /// A widget that uses the table layout algorithm for its children.
 ///
-/// For details about the table layout algorithm, see [RenderTable].
+/// If you only have one row, the [Row] widget is more appropriate. If you only
+/// have one column, the [Block] or [Column] widgets will be more appropriate.
+///
+/// Rows size vertically based on their contents. To control the column widths,
+/// use the [columnWidths] property.
+///
+/// For more details about the table layout algorithm, see [RenderTable].
 /// To control the alignment of children, see [TableCell].
 class Table extends RenderObjectWidget {
   /// Creates a table.
@@ -89,27 +100,71 @@ class Table extends RenderObjectWidget {
     this.textBaseline
   }) : children = children,
        _rowDecorations = children.any((TableRow row) => row.decoration != null)
-                         ? children.map/*<Decoration>*/((TableRow row) => row.decoration).toList()
+                         ? children.map/*<Decoration>*/((TableRow row) => row.decoration).toList(growable: false)
                          : null,
        super(key: key) {
     assert(children != null);
     assert(defaultColumnWidth != null);
     assert(defaultVerticalAlignment != null);
-    assert(!children.any((TableRow row) => row.children.any((Widget cell) => cell == null)));
+    assert(() {
+      if (children.any((TableRow row) => row.children.any((Widget cell) => cell == null))) {
+        throw new FlutterError(
+          'One of the children of one of the rows of the table was null.\n'
+          'The children of a TableRow must not be null.'
+        );
+      }
+      return true;
+    });
     assert(() {
       List<Widget> flatChildren = children.expand((TableRow row) => row.children).toList(growable: false);
-      return !debugChildrenHaveDuplicateKeys(this, flatChildren);
+      if (debugChildrenHaveDuplicateKeys(this, flatChildren)) {
+        throw new FlutterError(
+          'Two or more cells in this Table contain widgets with the same key.\n'
+          'Every widget child of every TableRow in a Table must have different keys. The cells of a Table are '
+          'flattened out for processing, so separate cells cannot have duplicate keys even if they are in '
+          'different rows.'
+        );
+      }
+      return true;
+    });
+    assert(() {
+      if (children.any((TableRow row1) => row1.key != null && children.any((TableRow row2) => row1 != row2 && row1.key == row2.key))) {
+        throw new FlutterError(
+          'Two or more TableRow children of this Table had the same key.\n'
+          'All the keyed TableRow children of a Table must have different Keys.'
+        );
+      }
+      return true;
+    });
+    assert(() {
+      if (children.length > 0) {
+        final int cellCount = children.first.children.length;
+        if (children.any((TableRow row) => row.children.length != cellCount)) {
+          throw new FlutterError(
+            'Table contains irregular row lengths.\n'
+            'Every TableRow in a Table must have the same number of children, so that every cell is filled. '
+            'Otherwise, the table will contain holes.'
+          );
+        }
+      }
+      return true;
     });
-    assert(!children.any((TableRow row1) => row1.key != null && children.any((TableRow row2) => row1 != row2 && row1.key == row2.key)));
   }
 
   /// The rows of the table.
+  ///
+  /// Every row in a table must have the same number of children, and all the
+  /// children must be non-null.
   final List<TableRow> children;
 
   /// How the horizontal extents of the columns of this table should be determined.
   ///
   /// If the [Map] has a null entry for a given column, the table uses the
-  /// [defaultColumnWidth] instead.
+  /// [defaultColumnWidth] instead. By default, that uses flex sizing to
+  /// distribute free space equally among the columns.
+  ///
+  /// The [FixedColumnWidth] class can be used to specify a specific width in
+  /// pixels. That is the cheapest way to size a table's columns.
   ///
   /// The layout performance of the table depends critically on which column
   /// sizing algorithms are used here. In particular, [IntrinsicColumnWidth] is