Add some more documentation. (#14717)

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

@@ -29,6 +29,14 @@ const double _kForegroundScreenOpacityFraction = 0.7;
 ///    the iOS design specific chrome.
 ///  * <https://developer.apple.com/ios/human-interface-guidelines/controls/pickers/>
 class CupertinoPicker extends StatefulWidget {
+  /// Creates a control used for selecting values.
+  ///
+  /// The [diameterRatio] and [itemExtent] arguments must not be null. The
+  /// [itemExtent] must be greater than zero.
+  ///
+  /// The [backgroundColor] defaults to light gray. It can be set to null to
+  /// disable the background painting entirely; this is mildly more efficient
+  /// than using [Colors.transparent].
   const CupertinoPicker({
     Key key,
     this.diameterRatio: _kDefaultDiameterRatio,
@@ -55,6 +63,9 @@ class CupertinoPicker extends StatefulWidget {
   /// Background color behind the children.
   ///
   /// Defaults to a gray color in the iOS color palette.
+  ///
+  /// This can be set to null to disable the background painting entirely; this
+  /// is mildly more efficient than using [Colors.transparent].
   final Color backgroundColor;
 
   /// A [FixedExtentScrollController] to read and control the current item.
@@ -164,26 +175,30 @@ class _CupertinoPickerState extends State<CupertinoPicker> {
 
   @override
   Widget build(BuildContext context) {
-    return new DecoratedBox(
-      decoration: new BoxDecoration(
-        color: widget.backgroundColor,
-      ),
-      child: new Stack(
-        children: <Widget>[
-          new Positioned.fill(
-            child: new ListWheelScrollView(
-              controller: widget.scrollController,
-              physics: const FixedExtentScrollPhysics(),
-              diameterRatio: widget.diameterRatio,
-              itemExtent: widget.itemExtent,
-              onSelectedItemChanged: _handleSelectedItemChanged,
-              children: widget.children,
-            ),
+    Widget result = new Stack(
+      children: <Widget>[
+        new Positioned.fill(
+          child: new ListWheelScrollView(
+            controller: widget.scrollController,
+            physics: const FixedExtentScrollPhysics(),
+            diameterRatio: widget.diameterRatio,
+            itemExtent: widget.itemExtent,
+            onSelectedItemChanged: _handleSelectedItemChanged,
+            children: widget.children,
           ),
-          _buildGradientScreen(),
-          _buildMagnifierScreen(),
-        ],
-      ),
+        ),
+        _buildGradientScreen(),
+        _buildMagnifierScreen(),
+      ],
     );
+    if (widget.backgroundColor != null) {
+      result = new DecoratedBox(
+        decoration: new BoxDecoration(
+          color: widget.backgroundColor,
+        ),
+        child: result,
+      );
+    }
+    return result;
   }
 }

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

@@ -37,12 +37,13 @@ enum _ScaffoldSlot {
   statusBar,
 }
 
-/// Geometry information for scaffold components.
+/// Geometry information for [Scaffold] components.
 ///
-/// To get a [ValueNotifier] for the scaffold geometry call
-/// [Scaffold.geometryOf].
+/// To get a [ValueNotifier] for the scaffold geometry of a given
+/// [BuildContext], use [Scaffold.geometryOf].
 @immutable
 class ScaffoldGeometry {
+  /// Create an object that describes the geometry of a [Scaffold].
   const ScaffoldGeometry({
     this.bottomNavigationBarTop,
     this.floatingActionButtonArea,

packages/flutter/lib/src/semantics/semantics.dart

@@ -1076,8 +1076,8 @@ class SemanticsNode extends AbstractNode with DiagnosticableTreeMixin {
   /// platform's accessibility services (e.g. VoiceOver on iOS and TalkBack on
   /// Android). This is used to determine the [nextNodeId] and [previousNodeId]
   /// during a semantics update.
-  SemanticsSortOrder _sortOrder;
   SemanticsSortOrder get sortOrder => _sortOrder;
+  SemanticsSortOrder _sortOrder;
 
   /// The ID of the next node in the traversal order after this node.
   ///
@@ -1089,6 +1089,7 @@ class SemanticsNode extends AbstractNode with DiagnosticableTreeMixin {
   /// If this is set to -1, it will indicate that there is no next node to
   /// the engine (i.e. this is the last node in the sort order). When it is
   /// null, it means that no semantics update has been built yet.
+  int get nextNodeId => _nextNodeId;
   int _nextNodeId;
   void _updateNextNodeId(int value) {
     if (value == _nextNodeId)
@@ -1096,7 +1097,6 @@ class SemanticsNode extends AbstractNode with DiagnosticableTreeMixin {
     _nextNodeId = value;
     _markDirty();
   }
-  int get nextNodeId => _nextNodeId;
 
   /// The ID of the previous node in the traversal order before this node.
   ///
@@ -1108,6 +1108,7 @@ class SemanticsNode extends AbstractNode with DiagnosticableTreeMixin {
   /// If this is set to -1, it will indicate that there is no previous node to
   /// the engine (i.e. this is the first node in the sort order). When it is
   /// null, it means that no semantics update has been built yet.
+  int get previousNodeId => _previousNodeId;
   int _previousNodeId;
   void _updatePreviousNodeId(int value) {
     if (value == _previousNodeId)
@@ -1115,7 +1116,6 @@ class SemanticsNode extends AbstractNode with DiagnosticableTreeMixin {
     _previousNodeId = value;
     _markDirty();
   }
-  int get previousNodeId => _previousNodeId;
 
   /// The currently selected text (or the position of the cursor) within [value]
   /// if this node represents a text field.
@@ -2681,26 +2681,30 @@ String _concatStrings({
 ///    [SemanticsSortOrder] manages.
 ///  * [OrdinalSortKey] for a sort key that sorts using an ordinal.
 class SemanticsSortOrder extends Diagnosticable implements Comparable<SemanticsSortOrder> {
+  /// Creates an object that describes the sort order for a [Semantics] widget.
+  ///
   /// Only one of `key` or `keys` may be specified, but at least one must
   /// be specified. Specifying `key` is a shorthand for specifying
-  /// `keys = <SemanticsSortKey>[key]`.
+  /// `keys: <SemanticsSortKey>[key]`.
   ///
-  /// If [discardParentOrder] is set to true, then the
-  /// [SemanticsSortOrder.keys] will replace the list of keys from the parents
-  /// when merged, instead of extending them.
+  /// If [discardParentOrder] is set to true, then the [SemanticsSortOrder.keys]
+  /// will _replace_ the list of keys from the parents when merged, instead of
+  /// extending them.
   SemanticsSortOrder({
     SemanticsSortKey key,
     List<SemanticsSortKey> keys,
     this.discardParentOrder = false,
-  })
-    : assert(key != null || keys != null, 'One of key or keys must be specified.'),
-      assert(key == null || keys == null, 'Only one of key or keys may be specified.'),
-      keys = key == null ? keys : <SemanticsSortKey>[key];
+  }) : assert(key != null || keys != null, 'One of key or keys must be specified.'),
+       assert(key == null || keys == null, 'Only one of key or keys may be specified.'),
+       keys = key == null ? keys : <SemanticsSortKey>[key];
 
   /// Whether or not this order is to replace the keys above it in the
   /// semantics tree, or to be appended to them.
   final bool discardParentOrder;
 
+  /// The keys that should be used to sort this node.
+  ///
+  /// Typically only one key is provided, using the constructor's `key` argument.
   final List<SemanticsSortKey> keys;
 
   /// Merges two sort orders by concatenating their sort key lists. If
@@ -2763,6 +2767,8 @@ class SemanticsSortOrder extends Diagnosticable implements Comparable<SemanticsS
 ///  * [SemanticsSortOrder] which manages a list of sort keys.
 ///  * [OrdinalSortKey] for a sort key that sorts using an ordinal.
 abstract class SemanticsSortKey extends Diagnosticable implements Comparable<SemanticsSortKey> {
+  /// Abstract const constructor. This constructor enables subclasses to provide
+  /// const constructors so that they can be used in const expressions.
   const SemanticsSortKey({this.name});
 
   /// An optional name that will make this sort key only order itself
@@ -2774,14 +2780,21 @@ abstract class SemanticsSortKey extends Diagnosticable implements Comparable<Sem
 
   @override
   int compareTo(SemanticsSortKey other) {
-    if (other.runtimeType != runtimeType || other.name != name) {
+    if (other.runtimeType != runtimeType || other.name != name)
       return 0;
-    }
     return doCompare(other);
   }
 
+  /// The implementation of [compareTo].
+  ///
+  /// The argument is guaranteed to be the same type as this object.
+  ///
+  /// The method should return a negative number of this object is earlier in
+  /// the sort order than the argument; and a positive number if it comes later
+  /// in the sort order. Returning zero causes the system to default to
+  /// comparing the geometry of the nodes.
   @protected
-  int doCompare(SemanticsSortKey other);
+  int doCompare(covariant SemanticsSortKey other);
 
   @override
   void debugFillProperties(DiagnosticPropertiesBuilder description) {
@@ -2790,30 +2803,40 @@ abstract class SemanticsSortKey extends Diagnosticable implements Comparable<Sem
   }
 }
 
-/// A [SemanticsSortKey] that sorts simply based on the ordinal given it.
+/// A [SemanticsSortKey] that sorts simply based on the `double` value it is
+/// given.
 ///
 /// The [OrdinalSortKey] compares itself with other [OrdinalSortKey]s
 /// to sort based on the order it is given.
 ///
+/// The ordinal value `order` is typically an integer, though it can be
+/// fractional, e.g. in order to fit between two other consecutive integers. The
+/// value must be finite (it cannot be a NaN value or infinity).
+///
 /// See also:
 ///
 ///  * [SemanticsSortOrder] which manages a list of sort keys.
 class OrdinalSortKey extends SemanticsSortKey {
-  const OrdinalSortKey(this.order, {String name}) : super(name: name);
+  /// Creates a semantics sort key that uses a double as its key value.
+  ///
+  /// The [order] must be a finite number.
+  const OrdinalSortKey(
+    this.order, {
+    String name,
+  }) : assert(order != null),
+       assert(order > double.NEGATIVE_INFINITY),
+       assert(order < double.INFINITY),
+       super(name: name);
 
-  /// [order] is a double which describes the order in which this node
-  /// is traversed by the platform's accessibility services. Lower values
-  /// will be traversed first.
+  /// A double which describes the order in which this node is traversed by the
+  /// platform's accessibility services. Lower values will be traversed first.
   final double order;
 
   @override
-  int doCompare(SemanticsSortKey other) {
-    assert(other.runtimeType == runtimeType);
-    final OrdinalSortKey otherOrder = other;
-    if (otherOrder.order == null || order == null || otherOrder.order == order) {
+  int doCompare(OrdinalSortKey other) {
+    if (other.order == null || order == null || other.order == order)
       return 0;
-    }
-    return order.compareTo(otherOrder.order);
+    return order.compareTo(other.order);
   }
 
   @override

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

@@ -1869,10 +1869,11 @@ abstract class BuildContext {
   /// (directly or indirectly) from build methods, layout and paint callbacks, or
   /// from [State.didChangeDependencies].
   ///
-  /// This method should not be called from [State.deactivate] or [State.dispose]
-  /// because the element tree is no longer stable at that time. To refer to
-  /// an ancestor from one of those methods, save a reference to the ancestor
-  /// in [State.didChangeDependencies].
+  /// This method should not be called from [State.dispose] because the element
+  /// tree is no longer stable at that time. To refer to an ancestor from that
+  /// method, save a reference to the ancestor in [State.didChangeDependencies].
+  /// It is safe to use this method from [State.deactivate], which is called
+  /// whenever the widget is removed from the tree.
   ///
   /// It is also possible to call this from interaction event handlers (e.g.
   /// gesture callbacks) or timers, to obtain a value once, if that value is not
@@ -1896,10 +1897,12 @@ abstract class BuildContext {
   /// This method does not establish a relationship with the target in the way
   /// that [inheritFromWidgetOfExactType] does.
   ///
-  /// This method should not be called from [State.deactivate] or [State.dispose]
-  /// because the element tree is no longer stable at that time. To refer to
-  /// an ancestor from one of those methods, save a reference to the ancestor
-  /// by calling [inheritFromWidgetOfExactType] in [State.didChangeDependencies].
+  /// This method should not be called from [State.dispose] because the element
+  /// tree is no longer stable at that time. To refer to an ancestor from that
+  /// method, save a reference to the ancestor by calling
+  /// [inheritFromWidgetOfExactType] in [State.didChangeDependencies]. It is
+  /// safe to use this method from [State.deactivate], which is called whenever
+  /// the widget is removed from the tree.
   InheritedElement ancestorInheritedElementForWidgetOfExactType(Type targetType);
 
   /// Returns the nearest ancestor widget of the given type, which must be the
@@ -1918,7 +1921,7 @@ abstract class BuildContext {
   /// This method should not be called from [State.deactivate] or [State.dispose]
   /// because the widget tree is no longer stable at that time. To refer to
   /// an ancestor from one of those methods, save a reference to the ancestor
-  /// by calling [inheritFromWidgetOfExactType] in [State.didChangeDependencies].
+  /// by calling [ancestorWidgetOfExactType] in [State.didChangeDependencies].
   Widget ancestorWidgetOfExactType(Type targetType);
 
   /// Returns the [State] object of the nearest ancestor [StatefulWidget] widget
@@ -1944,12 +1947,14 @@ abstract class BuildContext {
   /// This method should not be called from [State.deactivate] or [State.dispose]
   /// because the widget tree is no longer stable at that time. To refer to
   /// an ancestor from one of those methods, save a reference to the ancestor
-  /// by calling [inheritFromWidgetOfExactType] in [State.didChangeDependencies].
+  /// by calling [ancestorStateOfType] in [State.didChangeDependencies].
   ///
-  /// Example:
+  /// ## Sample code
   ///
   /// ```dart
-  /// context.ancestorStateOfType(const TypeMatcher<ScrollableState>());
+  /// ScrollableState scrollable = context.ancestorStateOfType(
+  ///   const TypeMatcher<ScrollableState>(),
+  /// );
   /// ```
   State ancestorStateOfType(TypeMatcher matcher);
 
@@ -1975,14 +1980,14 @@ abstract class BuildContext {
   /// it is used by [Material] so that [InkWell] widgets can trigger the ink
   /// splash on the [Material]'s actual render object.
   ///
-  /// This method should not be called from [State.deactivate] or [State.dispose]
-  /// because the widget tree is no longer stable at that time. To refer to
-  /// an ancestor from one of those methods, save a reference to the ancestor
-  /// by calling [inheritFromWidgetOfExactType] in [State.didChangeDependencies].
-  ///
   /// Calling this method is relatively expensive (O(N) in the depth of the
   /// tree). Only call this method if the distance from this widget to the
   /// desired ancestor is known to be small and bounded.
+  ///
+  /// This method should not be called from [State.deactivate] or [State.dispose]
+  /// because the widget tree is no longer stable at that time. To refer to
+  /// an ancestor from one of those methods, save a reference to the ancestor
+  /// by calling [ancestorRenderObjectOfType] in [State.didChangeDependencies].
   RenderObject ancestorRenderObjectOfType(TypeMatcher matcher);
 
   /// Walks the ancestor chain, starting with the parent of this build context's
@@ -1998,7 +2003,7 @@ abstract class BuildContext {
   /// This method should not be called from [State.deactivate] or [State.dispose]
   /// because the element tree is no longer stable at that time. To refer to
   /// an ancestor from one of those methods, save a reference to the ancestor
-  /// by calling [inheritFromWidgetOfExactType] in [State.didChangeDependencies].
+  /// by calling [visitAncestorElements] in [State.didChangeDependencies].
   void visitAncestorElements(bool visitor(Element element));
 
   /// Walks the children of this widget.

packages/flutter/test/widgets/custom_painter_test.dart

@@ -347,8 +347,6 @@ void _defineTests() {
       ),
     ));
 
-    debugDumpSemanticsTree(DebugSemanticsDumpOrder.inverseHitTest);
-
     final Set<SemanticsAction> allActions = SemanticsAction.values.values.toSet()
       ..remove(SemanticsAction.showOnScreen); // showOnScreen is non user-exposed.
 
@@ -656,8 +654,9 @@ class _DiffTester {
       firstChild.visitChildren((SemanticsNode node) {
         if (node.key != null && idAssignments[node.key] != null) {
           expect(idAssignments[node.key], node.id, reason:
-            'Node with key ${node.key} was previously assigned id ${idAssignments[node.key]}. '
-            'After diffing the child list, its id changed to ${node.id}. Ids must be stable.');
+            'Node with key ${node.key} was previously assigned ID ${idAssignments[node.key]}. '
+            'After diffing the child list, its ID changed to ${node.id}. IDs must be stable.'
+          );
         }
         return true;
       });