diff --git a/packages/flutter/lib/src/cupertino/page.dart b/packages/flutter/lib/src/cupertino/page.dart index e77d11c3e76..59c27d347a6 100644 --- a/packages/flutter/lib/src/cupertino/page.dart +++ b/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 primaryRouteAnimation, - // Linear route animation from 0.0 to 1.0 when another screen is being pushed on top of this - // one. @required Animation 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 _secondaryPositionAnimation; final Animation _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 -/// calendar event etc by bringing in the next screen from the bottom. +/// An iOS-style transition used for summoning fullscreen dialogs. +/// +/// 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 animation, @@ -217,6 +226,8 @@ class CupertinoFullscreenDialogTransition extends StatelessWidget { super(key: key); final Animation _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 -/// animation progress. Used for iOS back gesture. +/// A controller for an iOS-style 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 diff --git a/packages/flutter/lib/src/material/back_button.dart b/packages/flutter/lib/src/material/back_button.dart index e0ca0fd3662..5ffea5606db 100644 --- a/packages/flutter/lib/src/material/back_button.dart +++ b/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. @@ -73,10 +73,11 @@ class BackButton extends StatelessWidget { /// /// * [AppBar], which automatically uses a [CloseButton] in its /// [AppBar.leading] slot when appropriate. -/// * [BackButton], which is more appropriate for middle nodes in the +/// * [BackButton], which is more appropriate for middle nodes in the /// 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 diff --git a/packages/flutter/lib/src/material/material.dart b/packages/flutter/lib/src/material/material.dart index 38b14e24b15..7c7f510d26a 100644 --- a/packages/flutter/lib/src/material/material.dart +++ b/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; } diff --git a/packages/flutter/lib/src/material/tabs.dart b/packages/flutter/lib/src/material/tabs.dart index 322f642d96c..f0d01f9c300 100644 --- a/packages/flutter/lib/src/material/tabs.dart +++ b/packages/flutter/lib/src/material/tabs.dart @@ -915,6 +915,7 @@ class _TabBarViewState extends State { /// /// 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. diff --git a/packages/flutter/lib/src/rendering/object.dart b/packages/flutter/lib/src/rendering/object.dart index 07746eeb073..d1cb3f55875 100644 --- a/packages/flutter/lib/src/rendering/object.dart +++ b/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 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 _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) { diff --git a/packages/flutter/lib/src/rendering/paragraph.dart b/packages/flutter/lib/src/rendering/paragraph.dart index 62791b992b0..a63fc409ac7 100644 --- a/packages/flutter/lib/src/rendering/paragraph.dart +++ b/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; diff --git a/packages/flutter/lib/src/rendering/wrap.dart b/packages/flutter/lib/src/rendering/wrap.dart index 9db2a34d690..62f67441c03 100644 --- a/packages/flutter/lib/src/rendering/wrap.dart +++ b/packages/flutter/lib/src/rendering/wrap.dart @@ -63,8 +63,26 @@ class WrapParentData extends ContainerBoxParentDataMixin { 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, RenderBoxContainerDefaultsMixin { + /// 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 children, Axis direction: Axis.horizontal, diff --git a/packages/flutter/lib/src/scheduler/ticker.dart b/packages/flutter/lib/src/scheduler/ticker.dart index 48a54ce41d3..615020ade0a 100644 --- a/packages/flutter/lib/src/scheduler/ticker.dart +++ b/packages/flutter/lib/src/scheduler/ticker.dart @@ -363,6 +363,8 @@ class TickerFuture implements Future { _secondaryCompleter?.completeError(new TickerCanceled(ticker)); } + /// A future that resolves when this future resolves or throws when the ticker + /// is canceled. Future get orCancel { if (_secondaryCompleter == null) { _secondaryCompleter = new Completer(); diff --git a/packages/flutter/lib/src/widgets/basic.dart b/packages/flutter/lib/src/widgets/basic.dart index b70e7719ec3..6aa90b6edcf 100644 --- a/packages/flutter/lib/src/widgets/basic.dart +++ b/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, diff --git a/packages/flutter/lib/src/widgets/preferred_size.dart b/packages/flutter/lib/src/widgets/preferred_size.dart index c79b01d9e9e..51de00182ca 100644 --- a/packages/flutter/lib/src/widgets/preferred_size.dart +++ b/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 -/// the child's layout in any way. It just advertises a default size which -/// can be used by the parent. +/// This widget does not impose any constraints on its child, and it doesn't +/// affect the child's layout in any way. It just advertises a preferred size +/// 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 diff --git a/packages/flutter/lib/src/widgets/sliver.dart b/packages/flutter/lib/src/widgets/sliver.dart index 46668f0f86b..3952823ce43 100644 --- a/packages/flutter/lib/src/widgets/sliver.dart +++ b/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, diff --git a/packages/flutter/test/services/platform_channel_test.dart b/packages/flutter/test/services/platform_channel_test.dart index d141c4f797d..1f17812cbae 100644 --- a/packages/flutter/test/services/platform_channel_test.dart +++ b/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([null]); } else if (methodCall['method'] == 'cancel') { - cancelled = true; + canceled = true; return jsonMessage.encodeMessage([null]); } else { fail('Expected listen or cancel'); @@ -191,7 +191,7 @@ void main() { final List events = await channel.receiveBroadcastStream('hello').toList(); expect(events, orderedEquals(['hello1', 'hello2'])); await new Future.delayed(Duration.ZERO); - expect(cancelled, isTrue); + expect(canceled, isTrue); }); }); }