Document remaining non-scrolling symbols (#9667)

This patch finishes documenting all the symbols except for those related to
scrolling.

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

@@ -137,20 +137,24 @@ class _CupertinoEdgeShadowPainter extends BoxPainter {
   }
 }
 
-/// Provides the native iOS page transition animation.
+/// Provides an iOS-style page transition animation.
 ///
 /// The page slides in from the right and exits in reverse. It also shifts to the left in
 /// a parallax motion when another page enters to cover it.
 class CupertinoPageTransition extends StatelessWidget {
+  /// Creates an iOS-style page transition.
+  ///
+  ///  * `primaryRouteAnimation` is a linear route animation from 0.0 to 1.0
+  ///    when this screen is being pushed.
+  ///  * `secondaryRouteAnimation` is a linear route animation from 0.0 to 1.0
+  ///    when another screen is being pushed on top of this one.
+  ///  * `linearTransition` is whether to perform primary transition linearly.
+  ///    Used to precisely track back gesture drags.
   CupertinoPageTransition({
     Key key,
-    // Linear route animation from 0.0 to 1.0 when this screen is being pushed.
     @required Animation<double> primaryRouteAnimation,
-    // Linear route animation from 0.0 to 1.0 when another screen is being pushed on top of this
-    // one.
     @required Animation<double> secondaryRouteAnimation,
     @required this.child,
-    // Perform primary transition linearly. Use to precisely track back gesture drags.
     bool linearTransition,
   }) :
       _primaryPositionAnimation = linearTransition
@@ -182,6 +186,8 @@ class CupertinoPageTransition extends StatelessWidget {
   // When this page is becoming covered by another page.
   final Animation<FractionalOffset> _secondaryPositionAnimation;
   final Animation<Decoration> _primaryShadowAnimation;
+
+  /// The widget below this widget in the tree.
   final Widget child;
 
   @override
@@ -201,9 +207,12 @@ class CupertinoPageTransition extends StatelessWidget {
   }
 }
 
-/// Transitions used for summoning fullscreen dialogs in iOS such as creating a new
+/// An iOS-style transition used for summoning fullscreen dialogs.
-/// calendar event etc by bringing in the next screen from the bottom.
+///
+/// For example, used when creating a new calendar event by bringing in the next
+/// screen from the bottom.
 class CupertinoFullscreenDialogTransition extends StatelessWidget {
+  /// Creates an iOS-style transition used for summoning fullscreen dialogs.
   CupertinoFullscreenDialogTransition({
     Key key,
     @required Animation<double> animation,
@@ -217,6 +226,8 @@ class CupertinoFullscreenDialogTransition extends StatelessWidget {
        super(key: key);
 
   final Animation<FractionalOffset> _positionAnimation;
+
+  /// The widget below this widget in the tree.
   final Widget child;
 
   @override
@@ -228,9 +239,13 @@ class CupertinoFullscreenDialogTransition extends StatelessWidget {
   }
 }
 
-/// This class responds to drag gestures to control the route's transition
+/// A controller for an iOS-style back gesture.
-/// animation progress. Used for iOS back gesture.
+///
+/// Uses a drag gesture to control the route's transition animation progress.
 class CupertinoBackGestureController extends NavigationGestureController {
+  /// Creates a controller for an iOS-style back gesture.
+  ///
+  /// The [navigator] and [controller] arguments must not be null.
   CupertinoBackGestureController({
     @required NavigatorState navigator,
     @required this.controller,
@@ -238,6 +253,8 @@ class CupertinoBackGestureController extends NavigationGestureController {
     assert(controller != null);
   }
 
+  /// The animation controller that the route uses to drive its transition
+  /// animation.
   final AnimationController controller;
 
   @override

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

@@ -61,7 +61,7 @@ class BackButton extends StatelessWidget {
   }
 }
 
-/// A material design close button.
+/// A Material Design close button.
 ///
 /// A [CloseButton] is an [IconButton] with a "close" icon. When pressed, the
 /// close button calls [Navigator.maybePop] to return to the previous route.
@@ -77,6 +77,7 @@ class BackButton extends StatelessWidget {
 ///    navigation tree or where pages can be popped instantaneously with
 ///    no user data consequence.
 class CloseButton extends StatelessWidget {
+  /// Creates a Material Design close button.
   const CloseButton({ Key key }) : super(key: key);
 
   @override

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

@@ -190,7 +190,7 @@ class Material extends StatefulWidget {
   /// The default radius of an ink splash in logical pixels.
   static const double defaultSplashRadius = 35.0;
 
-  // Temporary flag used to enable the PhysicalModel shadow implementation.
+  /// Temporary flag used to enable the PhysicalModel shadow implementation.
   static bool debugEnablePhysicalModel = false;
 }
 

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

@@ -915,6 +915,7 @@ class _TabBarViewState extends State<TabBarView> {
 ///
 /// Used by [TabPageSelector] to indicate the selected page.
 class TabPageSelectorIndicator extends StatelessWidget {
+  /// Creates an indicator used by [TabPageSelector].
   const TabPageSelectorIndicator({ Key key, this.backgroundColor, this.borderColor }) : super(key: key);
 
   /// The indicator circle's background color.

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

@@ -2685,6 +2685,12 @@ abstract class RenderObject extends AbstractNode implements HitTestTarget {
 ///
 /// Provides a child model for a render object subclass that has a unique child.
 abstract class RenderObjectWithChildMixin<ChildType extends RenderObject> implements RenderObject {
+  /// Checks whether the given render object has the correct [runtimeType] to be
+  /// a child of this render object.
+  ///
+  /// Does nothing if assertions are disabled.
+  ///
+  /// Always returns true.
   bool debugValidateChild(RenderObject child) {
     assert(() {
       if (child is! ChildType) {
@@ -2811,6 +2817,12 @@ abstract class ContainerRenderObjectMixin<ChildType extends RenderObject, Parent
   /// The number of children.
   int get childCount => _childCount;
 
+  /// Checks whether the given render object has the correct [runtimeType] to be
+  /// a child of this render object.
+  ///
+  /// Does nothing if assertions are disabled.
+  ///
+  /// Always returns true.
   bool debugValidateChild(RenderObject child) {
     assert(() {
       if (child is! ChildType) {

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

@@ -190,6 +190,9 @@ class RenderParagraph extends RenderBox {
   bool _hasVisualOverflow = false;
   ui.Shader _overflowShader;
 
+  /// Whether this paragraph currently has a [ui.Shader] for its overflow effect.
+  ///
+  /// Used to test this object. Not for use in production.
   @visibleForTesting
   bool get debugHasOverflowShader => _overflowShader != null;
 

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

@@ -63,8 +63,26 @@ class WrapParentData extends ContainerBoxParentDataMixin<RenderBox> {
   int _runIndex = 0;
 }
 
+/// Displays its children in multiple horizontal or vertical runs.
+///
+/// A [RenderWrap] lays out each child and attempts to place the child adjacent
+/// to the previous child in the main axis, given by [direction], leaving
+/// [spacing] space in between. If there is not enough space to fit the child,
+/// [RenderWrap] creates a new _run_ adjacent to the existing children in the
+/// cross axis.
+///
+/// After all the children have been allocated to runs, the children within the
+/// runs are positioned according to the [alignment] in the main axis and
+/// according to the [crossAxisAlignment] in the cross axis.
+///
+/// The runs themselves are then positioned in the cross axis according to the
+/// [runSpacing] and [runAlignment].
 class RenderWrap extends RenderBox with ContainerRenderObjectMixin<RenderBox, WrapParentData>,
                                         RenderBoxContainerDefaultsMixin<RenderBox, WrapParentData> {
+  /// Creates a wrap render object.
+  ///
+  /// By default, the wrap layout is horizontal and both the children and the
+  /// runs are aligned to the start.
   RenderWrap({
     List<RenderBox> children,
     Axis direction: Axis.horizontal,

packages/flutter/lib/src/scheduler/ticker.dart

@@ -363,6 +363,8 @@ class TickerFuture implements Future<Null> {
     _secondaryCompleter?.completeError(new TickerCanceled(ticker));
   }
 
+  /// A future that resolves when this future resolves or throws when the ticker
+  /// is canceled.
   Future<Null> get orCancel {
     if (_secondaryCompleter == null) {
       _secondaryCompleter = new Completer<Null>();

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

@@ -2284,7 +2284,24 @@ class Expanded extends Flexible {
   }) : super(key: key, flex: flex, fit: FlexFit.tight, child: child);
 }
 
+/// A widget that displays its children in multiple horizontal or vertical runs.
+///
+/// A [Wrap] lays out each child and attempts to place the child adjacent to the
+/// previous child in the main axis, given by [direction], leaving [spacing]
+/// space in between. If there is not enough space to fit the child, [Wrap]
+/// creates a new _run_ adjacent to the existing children in the cross axis.
+///
+/// After all the children have been allocated to runs, the children within the
+/// runs are positioned according to the [alignment] in the main axis and
+/// according to the [crossAxisAlignment] in the cross axis.
+///
+/// The runs themselves are then positioned in the cross axis according to the
+/// [runSpacing] and [runAlignment].
 class Wrap extends MultiChildRenderObjectWidget {
+  /// Creates a wrap layout.
+  ///
+  /// By default, the wrap layout is horizontal and both the children and the
+  /// runs are aligned to the start.
   Wrap({
     Key key,
     this.direction: Axis.horizontal,

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

@@ -29,11 +29,11 @@ abstract class PreferredSizeWidget implements Widget {
   Size get preferredSize;
 }
 
-/// Give an arbitrary widget a preferred size.
+/// A widget with a preferred size.
 ///
-/// This class does not impose any constraints on its child, it doesn't affect
+/// This widget does not impose any constraints on its child, and it doesn't
-/// the child's layout in any way. It just advertises a default size which
+/// affect the child's layout in any way. It just advertises a preferred size
-/// can be used by the parent.
+/// which can be used by the parent.
 ///
 /// See also:
 ///
@@ -42,12 +42,14 @@ abstract class PreferredSizeWidget implements Widget {
 ///    its preferred size.
 ///  * [AppBar] and [TabBar], which implement PreferredSizeWidget.
 class PreferredSize extends StatelessWidget implements PreferredSizeWidget {
+  /// Creates a widget that has a preferred size.
   const PreferredSize({
     Key key,
     @required this.child,
     @required this.preferredSize,
   }) : super(key: key);
 
+  /// The widget below this widget in the tree.
   final Widget child;
 
   @override

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

@@ -692,6 +692,7 @@ class SliverMultiBoxAdaptorElement extends RenderObjectElement implements Render
 ///  * [SliverList], which shows a list of variable-sized children in a
 ///    viewport.
 class SliverFillRemaining extends SingleChildRenderObjectWidget {
+  /// Creates a sliver that fills the remaining space in the viewport.
   const SliverFillRemaining({
     Key key,
     Widget child,

packages/flutter/test/services/platform_channel_test.dart

@@ -169,7 +169,7 @@ void main() {
           (ByteData reply) {},
         );
       }
-      bool cancelled = false;
+      bool canceled = false;
       BinaryMessages.setMockMessageHandler(
         'ch',
         (ByteData message) async {
@@ -181,7 +181,7 @@ void main() {
             emitEvent(null);
             return jsonMessage.encodeMessage(<dynamic>[null]);
           } else if (methodCall['method'] == 'cancel') {
-            cancelled = true;
+            canceled = true;
             return jsonMessage.encodeMessage(<dynamic>[null]);
           } else {
             fail('Expected listen or cancel');
@@ -191,7 +191,7 @@ void main() {
       final List<dynamic> events = await channel.receiveBroadcastStream('hello').toList();
       expect(events, orderedEquals(<String>['hello1', 'hello2']));
       await new Future<Null>.delayed(Duration.ZERO);
-      expect(cancelled, isTrue);
+      expect(canceled, isTrue);
     });
   });
 }