Merge pull request #847 from abarth/enum_docs

Add more dartdoc

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

@@ -902,12 +902,17 @@ class BlockBody extends MultiChildRenderObjectWidget {
   }
 }
 
+/// Uses the stack layout algorithm for its children.
+///
+/// For details about the stack layout algorithm, see [RenderStack]. To control
+/// the position of child widgets, see the [Positioned] widget.
 class Stack extends MultiChildRenderObjectWidget {
   Stack(List<Widget> children, {
     Key key,
     this.alignment: const FractionalOffset(0.0, 0.0)
   }) : super(key: key, children: children);
 
+  /// How to align the non-positioned children in the stack.
   final FractionalOffset alignment;
 
   RenderStack createRenderObject() => new RenderStack(alignment: alignment);
@@ -917,6 +922,7 @@ class Stack extends MultiChildRenderObjectWidget {
   }
 }
 
+/// A [Stack] that shows a single child at once.
 class IndexedStack extends MultiChildRenderObjectWidget {
   IndexedStack(List<Widget> children, {
     Key key,
@@ -924,7 +930,10 @@ class IndexedStack extends MultiChildRenderObjectWidget {
     this.index: 0
   }) : super(key: key, children: children);
 
+  /// The index of the child to show.
   final int index;
+
+  /// How to align the non-positioned children in the stack.
   final FractionalOffset alignment;
 
   RenderIndexedStack createRenderObject() => new RenderIndexedStack(index: index, alignment: alignment);
@@ -936,6 +945,11 @@ class IndexedStack extends MultiChildRenderObjectWidget {
   }
 }
 
+/// Controls where a child of a [Stack] is positioned.
+///
+/// This widget must be a descendant of a [Stack], and the path from this widget
+/// to its enclosing [Stack] must contain only components (e.g., not other
+/// kinds of widgets, like [RenderObjectWidget]s).
 class Positioned extends ParentDataWidget {
   Positioned({
     Key key,
@@ -963,12 +977,26 @@ class Positioned extends ParentDataWidget {
        bottom = null,
        super(key: key, child: child);
 
+  /// The offset of the child's top edge from the top of the stack.
   final double top;
+
+  /// The offset of the child's right edge from the right of the stack.
   final double right;
+
+  /// The offset of the child's bottom edge from the bottom of the stack.
   final double bottom;
+
+  /// The offset of the child's left edge from the left of the stack.
   final double left;
 
+  /// The child's width.
+  ///
+  /// Ignored if both left and right are non-null.
   final double width;
+
+  /// The child's height.
+  ///
+  /// Ignored if both top and bottom are non-null.
   final double height;
 
   void debugValidateAncestor(Widget ancestor) {
@@ -1037,6 +1065,9 @@ class Positioned extends ParentDataWidget {
   }
 }
 
+/// Uses the grid layout algorithm for its children.
+///
+/// For details about the grid layout algorithm, see [RenderGrid].
 class Grid extends MultiChildRenderObjectWidget {
   Grid(List<Widget> children, { Key key, this.maxChildExtent })
     : super(key: key, children: children) {
@@ -1052,6 +1083,10 @@ class Grid extends MultiChildRenderObjectWidget {
   }
 }
 
+/// Uses the flex layout algorithm for its children.
+///
+/// For details about the flex layout algorithm, see [RenderFlex]. To control
+/// the flex of child widgets, see the [Flexible] widget.
 class Flex extends MultiChildRenderObjectWidget {
   Flex(List<Widget> children, {
     Key key,
@@ -1080,6 +1115,10 @@ class Flex extends MultiChildRenderObjectWidget {
   }
 }
 
+/// Lays out child elements in a row.
+///
+/// For details about the flex layout algorithm, see [RenderFlex]. To control
+/// the flex of child widgets, see the [Flexible] widget.
 class Row extends Flex {
   Row(List<Widget> children, {
     Key key,
@@ -1089,6 +1128,10 @@ class Row extends Flex {
   }) : super(children, key: key, direction: FlexDirection.horizontal, justifyContent: justifyContent, alignItems: alignItems, textBaseline: textBaseline);
 }
 
+/// Lays out child elements in a column.
+///
+/// For details about the flex layout algorithm, see [RenderFlex]. To control
+/// the flex of child widgets, see the [Flexible] widget.
 class Column extends Flex {
   Column(List<Widget> children, {
     Key key,
@@ -1098,10 +1141,22 @@ class Column extends Flex {
   }) : super(children, key: key, direction: FlexDirection.vertical, justifyContent: justifyContent, alignItems: alignItems, textBaseline: textBaseline);
 }
 
+/// Controls how a child of a [Flex], [Row], or [Column] flexes.
+///
+/// This widget must be a descendant of a [Flex], [Row], or [Column], and the
+/// path from this widget to its enclosing [Flex], [Row], or [Column] must
+/// contain only components (e.g., not other kinds of widgets, like
+/// [RenderObjectWidget]s).
 class Flexible extends ParentDataWidget {
   Flexible({ Key key, this.flex: 1, Widget child })
     : super(key: key, child: child);
 
+  /// The flex factor to use for this child
+  ///
+  /// If null, the child is inflexible and determines its own size. If non-null,
+  /// the child is flexible and its extent in the main axis is determined by
+  /// dividing the free space (after placing the inflexible children)
+  /// according to the flex factors of the flexible children.
   final int flex;
 
   void debugValidateAncestor(Widget ancestor) {

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

@@ -19,15 +19,33 @@ const double _kMinFlingVelocityDelta = 400.0;
 const double _kFlingVelocityScale = 1.0 / 300.0;
 const double _kDismissCardThreshold = 0.4;
 
+/// The direction in which a [Dismissable] can be dismissed.
 enum DismissDirection {
+  /// The [Dismissable] can be dismissed by dragging either up or down.
   vertical,
+
+  /// The [Dismissable] can be dismissed by dragging either left or right.
   horizontal,
+
+  /// The [Dismissable] can be dismissed by dragging left only.
   left,
+
+  /// The [Dismissable] can be dismissed by dragging right only.
   right,
+
+  /// The [Dismissable] can be dismissed by dragging up only.
   up,
+
+  /// The [Dismissable] can be dismissed by dragging down only.
   down
 }
 
+/// Can be dismissed by dragging in one or more directions.
+///
+/// The child is draggable in the indicated direction(s). When released (or
+/// flung), the child disappears off the edge and the dismissable widget
+/// animates its height (or width, whichever is perpendicular to the dismiss
+/// direction) to zero.
 class Dismissable extends StatefulComponent {
   Dismissable({
     Key key,
@@ -38,8 +56,14 @@ class Dismissable extends StatefulComponent {
   }) : super(key: key);
 
   final Widget child;
+
+  /// Called when the widget changes size (i.e., when contracting after being dismissed).
   final VoidCallback onResized;
+
+  /// Called when the widget has been dismissed.
   final VoidCallback onDismissed;
+
+  /// The direction in which the widget can be dismissed.
   final DismissDirection direction;
 
   _DismissableState createState() => new _DismissableState();

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

@@ -18,6 +18,7 @@ typedef void DragTargetAccept<T>(T data);
 typedef Widget DragTargetBuilder<T>(BuildContext context, List<T> candidateData, List<dynamic> rejectedData);
 typedef void DragStartCallback(Point position, int pointer);
 
+/// Where the [Draggable] should be anchored during a drag.
 enum DragAnchor {
   /// Display the feedback anchored at the position of the original child. If
   /// feedback is identical to the child, then this means the feedback will
@@ -37,6 +38,7 @@ enum DragAnchor {
   pointer,
 }
 
+/// Subclass this component to customize the gesture used to start a drag.
 abstract class DraggableBase<T> extends StatefulComponent {
   DraggableBase({
     Key key,
@@ -52,12 +54,16 @@ abstract class DraggableBase<T> extends StatefulComponent {
 
   final T data;
   final Widget child;
+
+  /// The widget to show when a drag is under way.
   final Widget feedback;
 
   /// The feedbackOffset can be used to set the hit test target point for the
   /// purposes of finding a drag target. It is especially useful if the feedback
   /// is transformed compared to the child.
   final Offset feedbackOffset;
+
+  /// Where this widget should be anchored during a drag.
   final DragAnchor dragAnchor;
 
   /// Should return a GestureRecognizer instance that is configured to call the starter
@@ -69,6 +75,7 @@ abstract class DraggableBase<T> extends StatefulComponent {
   _DraggableState<T> createState() => new _DraggableState<T>();
 }
 
+/// Makes its child draggable starting from tap down.
 class Draggable<T> extends DraggableBase<T> {
   Draggable({
     Key key,
@@ -94,6 +101,7 @@ class Draggable<T> extends DraggableBase<T> {
   }
 }
 
+/// Makes its child draggable starting from long press.
 class LongPressDraggable<T> extends DraggableBase<T> {
   LongPressDraggable({
     Key key,
@@ -181,7 +189,7 @@ class _DraggableState<T> extends State<DraggableBase<T>> implements GestureArena
   }
 }
 
-
+/// Receives data when a [Draggable] widget is dropped.
 class DragTarget<T> extends StatefulComponent {
   const DragTarget({
     Key key,
@@ -190,8 +198,17 @@ class DragTarget<T> extends StatefulComponent {
     this.onAccept
   }) : super(key: key);
 
+  /// Called to build the contents of this widget.
+  ///
+  /// The builder can build different widgets depending on what is being dragged
+  /// into this drag target.
   final DragTargetBuilder<T> builder;
+
+  /// Called to determine whether this widget is interested in receiving a given
+  /// piece of data being dragged over this drag target.
   final DragTargetWillAccept<T> onWillAccept;
+
+  /// Called when an acceptable piece of data was dropped over this drag target.
   final DragTargetAccept<T> onAccept;
 
   _DragTargetState<T> createState() => new _DragTargetState<T>();