Update documentation (#61424)

packages/flutter/lib/src/gestures/events.dart

@@ -197,6 +197,8 @@ bool isSingleButton(int buttons) => buttons != 0 && (smallestButton(buttons) ==
 /// See also:
 ///
 ///  * [Window.devicePixelRatio], which defines the device's current resolution.
+///  * [Listener], a widget that calls callbacks in response to common pointer
+///    events.
 @immutable
 abstract class PointerEvent with Diagnosticable {
   /// Abstract const constructor. This constructor enables subclasses to provide
@@ -726,6 +728,8 @@ class PointerRemovedEvent extends PointerEvent {
 ///  * [PointerExitEvent], which reports when the pointer has left an object.
 ///  * [PointerMoveEvent], which reports movement while the pointer is in
 ///    contact with the device.
+///  * [Listener.onPointerHover], which allows callers to be notified of these
+///    events in a widget tree.
 class PointerHoverEvent extends PointerEvent {
   /// Creates a pointer hover event.
   ///
@@ -834,6 +838,8 @@ class PointerHoverEvent extends PointerEvent {
 ///  * [PointerExitEvent], which reports when the pointer has left an object.
 ///  * [PointerMoveEvent], which reports movement while the pointer is in
 ///    contact with the device.
+///  * [Listener.onPointerEnter], which allows callers to be notified of these
+///    events in a widget tree.
 class PointerEnterEvent extends PointerEvent {
   /// Creates a pointer enter event.
   ///
@@ -983,6 +989,8 @@ class PointerEnterEvent extends PointerEvent {
 ///  * [PointerEnterEvent], which reports when the pointer has entered an object.
 ///  * [PointerMoveEvent], which reports movement while the pointer is in
 ///    contact with the device.
+///  * [Listener.onPointerExit], which allows callers to be notified of these
+///    events in a widget tree.
 class PointerExitEvent extends PointerEvent {
   /// Creates a pointer exit event.
   ///
@@ -1123,6 +1131,11 @@ class PointerExitEvent extends PointerEvent {
 }
 
 /// The pointer has made contact with the device.
+///
+/// See also:
+///
+///  * [Listener.onPointerDown], which allows callers to be notified of these
+///    events in a widget tree.
 class PointerDownEvent extends PointerEvent {
   /// Creates a pointer down event.
   ///
@@ -1216,6 +1229,8 @@ class PointerDownEvent extends PointerEvent {
 ///
 ///  * [PointerHoverEvent], which reports movement while the pointer is not in
 ///    contact with the device.
+///  * [Listener.onPointerMove], which allows callers to be notified of these
+///    events in a widget tree.
 class PointerMoveEvent extends PointerEvent {
   /// Creates a pointer move event.
   ///
@@ -1322,6 +1337,11 @@ class PointerMoveEvent extends PointerEvent {
 }
 
 /// The pointer has stopped making contact with the device.
+///
+/// See also:
+///
+///  * [Listener.onPointerUp], which allows callers to be notified of these
+///    events in a widget tree.
 class PointerUpEvent extends PointerEvent {
   /// Creates a pointer up event.
   ///
@@ -1417,6 +1437,11 @@ class PointerUpEvent extends PointerEvent {
 /// Pointer signals are events that originate from the pointer but don't change
 /// the state of the pointer itself, and are discrete rather than needing to be
 /// interpreted in the context of a series of events.
+///
+/// See also:
+///
+///  * [Listener.onPointerSignal], which allows callers to be notified of these
+///    events in a widget tree.
 abstract class PointerSignalEvent extends PointerEvent {
   /// Abstract const constructor. This constructor enables subclasses to provide
   /// const constructors so that they can be used in const expressions.
@@ -1447,6 +1472,11 @@ abstract class PointerSignalEvent extends PointerEvent {
 ///
 /// Scrolling the scroll wheel on a mouse is an example of an event that
 /// would create a [PointerScrollEvent].
+///
+/// See also:
+///
+///  * [Listener.onPointerSignal], which allows callers to be notified of these
+///    events in a widget tree.
 class PointerScrollEvent extends PointerSignalEvent {
   /// Creates a pointer scroll event.
   ///
@@ -1506,6 +1536,11 @@ class PointerScrollEvent extends PointerSignalEvent {
 }
 
 /// The input from the pointer is no longer directed towards this receiver.
+///
+/// See also:
+///
+///  * [Listener.onPointerCancel], which allows callers to be notified of these
+///    events in a widget tree.
 class PointerCancelEvent extends PointerEvent {
   /// Creates a pointer cancel event.
   ///

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

@@ -27,6 +27,8 @@ const Duration _kDefaultHighlightFadeDuration = Duration(milliseconds: 200);
 ///  * [Material], which is the widget on which the ink highlight is painted.
 ///  * [InkSplash], which is an ink feature that shows a reaction to user input
 ///    on a [Material].
+///  * [Ink], a convenience widget for drawing images and other decorations on
+///    Material widgets.
 class InkHighlight extends InteractiveInkFeature {
   /// Begin a highlight animation.
   ///

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

@@ -97,6 +97,8 @@ class _InkSplashFactory extends InteractiveInkFeatureFactory {
 ///  * [Material], which is the widget on which the ink splash is painted.
 ///  * [InkHighlight], which is an ink feature that emphasizes a part of a
 ///    [Material].
+///  * [Ink], a convenience widget for drawing images and other decorations on
+///    Material widgets.
 class InkSplash extends InteractiveInkFeature {
   /// Begin a splash, centered at position relative to [referenceBox].
   ///

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

@@ -796,6 +796,35 @@ class ListTile extends StatelessWidget {
   ///
   /// By default the selected color is the theme's primary color. The selected color
   /// can be overridden with a [ListTileTheme].
+  ///
+  /// {@tool dartpad --template=stateful_widget_scaffold}
+  ///
+  /// Here is an example of using a [StatefulWidget] to keep track of the
+  /// selected index, and using that to set the `selected` property on the
+  /// corresponding [ListTile].
+  ///
+  /// ```dart
+  ///   int _selectedIndex;
+  ///
+  ///   @override
+  ///   Widget build(BuildContext context) {
+  ///     return ListView.builder(
+  ///       itemCount: 10,
+  ///       itemBuilder: (BuildContext context, int index) {
+  ///         return ListTile(
+  ///           title: Text('Item $index'),
+  ///           selected: index == _selectedIndex,
+  ///           onTap: () {
+  ///             setState(() {
+  ///               _selectedIndex = index;
+  ///             });
+  ///           },
+  ///         );
+  ///       },
+  ///     );
+  ///   }
+  /// ```
+  /// {@end-tool}
   final bool selected;
 
   /// The color for the tile's [Material] when it has the input focus.

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

@@ -117,7 +117,6 @@ abstract class MaterialInkController {
 /// and [ShapeBorder.lerp] between the previous and next [shape] values is
 /// supported. Shape changes are also animated for [animationDuration].
 ///
-///
 /// ## Shape
 ///
 /// The shape for material is determined by [shape], [type], and [borderRadius].
@@ -150,6 +149,16 @@ abstract class MaterialInkController {
 /// features (e.g., ink splashes and ink highlights) won't move to account for
 /// the new layout.
 ///
+/// ## Painting over the material
+///
+/// Material widgets will often trigger reactions on their nearest material
+/// ancestor. For example, [ListTile.hoverColor] triggers a reaction on the
+/// tile's material when a pointer is hovering over it. These reactions will be
+/// obscured if any widget in between them and the material paints in such a
+/// way as to obscure the material (such as setting a [BoxDecoration.color] on
+/// a [DecoratedBox]). To avoid this behavior, use [InkDecoration] to decorate
+/// the material itself.
+///
 /// See also:
 ///
 ///  * [MergeableMaterial], a piece of material that can split and re-merge.

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

@@ -48,6 +48,22 @@ const Duration _kElevationDuration = Duration(milliseconds: 75);
 /// Outline buttons have a minimum size of 88.0 by 36.0 which can be overridden
 /// with [ButtonTheme].
 ///
+/// {@tool dartpad --template=stateless_widget_scaffold_center}
+///
+/// Here is an example of a basic [OutlineButton].
+///
+/// ```dart
+///   Widget build(BuildContext context) {
+///     return OutlineButton(
+///       onPressed: () {
+///         print('Received click');
+///       },
+///       child: Text('Click Me'),
+///     );
+///   }
+/// ```
+/// {@end-tool}
+///
 /// See also:
 ///
 ///  * [RaisedButton], a filled material design button with a shadow.

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

@@ -178,7 +178,7 @@ class _RenderMenuItem extends RenderShiftedBox {
 ///
 /// Typically the [child] of a [PopupMenuItem] is a [Text] widget. More
 /// elaborate menus with icons can use a [ListTile]. By default, a
-/// [PopupMenuItem] is kMinInteractiveDimension pixels high. If you use a widget
+/// [PopupMenuItem] is [kMinInteractiveDimension] pixels high. If you use a widget
 /// with a different height, it must be specified in the [height] property.
 ///
 /// {@tool snippet}

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

@@ -1674,6 +1674,26 @@ class ScaffoldState extends State<Scaffold> with TickerProviderStateMixin {
   /// animation), use [removeCurrentSnackBar].
   ///
   /// See [Scaffold.of] for information about how to obtain the [ScaffoldState].
+  ///
+  /// {@tool dartpad --template=stateless_widget_scaffold_center}
+  ///
+  /// Here is an example of showing a [SnackBar] when the user presses a button.
+  ///
+  /// ```dart
+  ///   Widget build(BuildContext context) {
+  ///     return OutlineButton(
+  ///       onPressed: () {
+  ///         Scaffold.of(context).showSnackBar(
+  ///           SnackBar(
+  ///             content: Text('A SnackBar has been shown.'),
+  ///           ),
+  ///         );
+  ///       },
+  ///       child: Text('Show SnackBar'),
+  ///     );
+  ///   }
+  /// ```
+  /// {@end-tool}
   ScaffoldFeatureController<SnackBar, SnackBarClosedReason> showSnackBar(SnackBar snackbar) {
     _snackBarController ??= SnackBar.createAnimationController(vsync: this)
       ..addStatusListener(_handleSnackBarStatusChange);

packages/flutter/lib/src/painting/clip.dart

@@ -43,7 +43,7 @@ abstract class ClipContext {
     _clipAndPaint((bool doAntiAias) => canvas.clipPath(path, doAntiAlias: doAntiAias), clipBehavior, bounds, painter);
   }
 
-  /// Clip [canvas] with [Path] according to [RRect] and then paint. [canvas] is
+  /// Clip [canvas] with [Path] according to `rrect` and then paint. [canvas] is
   /// restored to the pre-clip status afterwards.
   ///
   /// `bounds` is the saveLayer bounds used for [Clip.antiAliasWithSaveLayer].
@@ -51,7 +51,7 @@ abstract class ClipContext {
     _clipAndPaint((bool doAntiAias) => canvas.clipRRect(rrect, doAntiAlias: doAntiAias), clipBehavior, bounds, painter);
   }
 
-  /// Clip [canvas] with [Path] according to [Rect] and then paint. [canvas] is
+  /// Clip [canvas] with [Path] according to `rect` and then paint. [canvas] is
   /// restored to the pre-clip status afterwards.
   ///
   /// `bounds` is the saveLayer bounds used for [Clip.antiAliasWithSaveLayer].

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

@@ -688,6 +688,8 @@ class BoxHitTestResult extends HitTestResult {
   /// the child speaks a different hit test protocol then the parent and the
   /// position is not required to do the actual hit testing in that protocol.
   ///
+  /// The function returns the return value of the `hitTest` callback.
+  ///
   /// {@tool snippet}
   /// This method is used in [RenderBox.hitTestChildren] when the child and
   /// parent don't share the same origin.
@@ -754,6 +756,8 @@ class BoxHitTestResult extends HitTestResult {
   ///
   /// A null value for `offset` is treated as if [Offset.zero] was provided.
   ///
+  /// The function returns the return value of the `hitTest` callback.
+  ///
   /// See also:
   ///
   ///  * [addWithPaintTransform], which takes a generic paint transform matrix and
@@ -1445,6 +1449,11 @@ abstract class RenderBox extends RenderObject {
   ///
   /// When the incoming argument is not finite, then they should return the
   /// actual intrinsic dimensions based on the contents, as any other box would.
+  ///
+  /// See also:
+  ///
+  ///  * [computeMaxIntrinsicWidth], which computes the smallest width beyond
+  ///    which increasing the width never decreases the preferred height.
   @protected
   double computeMinIntrinsicWidth(double height) {
     return 0.0;
@@ -1600,6 +1609,8 @@ abstract class RenderBox extends RenderObject {
   /// See also:
   ///
   ///  * [computeMinIntrinsicWidth], which has usage examples.
+  ///  * [computeMaxIntrinsicHeight], which computes the smallest height beyond
+  ///    which increasing the height never decreases the preferred width.
   @protected
   double computeMinIntrinsicHeight(double width) {
     return 0.0;
@@ -2160,6 +2171,9 @@ abstract class RenderBox extends RenderObject {
   /// Override this method if this render object can be hit even if its
   /// children were not hit.
   ///
+  /// Returns true if the specified `position` should be considered a hit
+  /// on this render object.
+  ///
   /// The caller is responsible for transforming [position] from global
   /// coordinates to its location relative to the origin of this [RenderBox].
   /// This [RenderBox] is responsible for checking whether the given position is
@@ -2173,18 +2187,21 @@ abstract class RenderBox extends RenderObject {
   /// Override this method to check whether any children are located at the
   /// given position.
   ///
+  /// Subclasses should return true if at least one child reported a hit at the
+  /// specified position.
+  ///
   /// Typically children should be hit-tested in reverse paint order so that
   /// hit tests at locations where children overlap hit the child that is
   /// visually "on top" (i.e., paints later).
   ///
   /// The caller is responsible for transforming [position] from global
   /// coordinates to its location relative to the origin of this [RenderBox].
-  /// This [RenderBox] is responsible for checking whether the given position is
-  /// within its bounds.
+  /// Likewise, this [RenderBox] is responsible for transforming the position
+  /// that it passes to its children when it calls [hitTest] on each child.
   ///
   /// If transforming is necessary, [HitTestResult.addWithPaintTransform],
   /// [HitTestResult.addWithPaintOffset], or [HitTestResult.addWithRawTransform] need
-  /// to be invoked by the caller to record the required transform operations
+  /// to be invoked by subclasses to record the required transform operations
   /// in the [HitTestResult]. These methods will also help with applying the
   /// transform to `position`.
   ///

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

@@ -185,8 +185,16 @@ enum CrossAxisAlignment {
 
   /// Place the children along the cross axis such that their baselines match.
   ///
-  /// If the main axis is vertical, then this value is treated like [start]
-  /// (since baselines are always horizontal).
+  /// Because baselines are always horizontal, this alignment is intended for
+  /// horizontal main axes. If the main axis is vertical, then this value is
+  /// treated like [start].
+  ///
+  /// For horizontal main axes, if the minimum height constraint passed to the
+  /// flex layout exceeds the intrinsic height of the cross axis, children will
+  /// be aligned as close to the top as they can be while honoring the baseline
+  /// alignment. In other words, the extra space will be below all the children.
+  ///
+  /// Children who report no baseline will be top-aligned.
   baseline,
 }
 
@@ -744,12 +752,10 @@ class RenderFlex extends RenderBox with ContainerRenderObjectMixin<RenderBox, Fl
         if (crossAxisAlignment == CrossAxisAlignment.stretch) {
           switch (_direction) {
             case Axis.horizontal:
-              innerConstraints = BoxConstraints(minHeight: constraints.maxHeight,
-                                                    maxHeight: constraints.maxHeight);
+              innerConstraints = BoxConstraints.tightFor(height: constraints.maxHeight);
               break;
             case Axis.vertical:
-              innerConstraints = BoxConstraints(minWidth: constraints.maxWidth,
-                                                    maxWidth: constraints.maxWidth);
+              innerConstraints = BoxConstraints.tightFor(width: constraints.maxWidth);
               break;
           }
         } else {

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

@@ -24,9 +24,14 @@ export 'package:flutter/painting.dart';
 
 /// Base class for data associated with a [RenderObject] by its parent.
 ///
-/// Some render objects wish to store data on their children, such as their
-/// input parameters to the parent's layout algorithm or their position relative
-/// to other children.
+/// Some render objects wish to store data on their children, such as the
+/// children's input parameters to the parent's layout algorithm or the
+/// children's position relative to other children.
+///
+/// See also:
+///
+///  * [RenderObject.setupParentData], which [RenderObject] subclasses may
+///    override to attach specific types of parent data to children.
 class ParentData {
   /// Called when the RenderObject is removed from the tree.
   @protected
@@ -710,6 +715,8 @@ abstract class Constraints {
 /// Signature for a function that is called for each [RenderObject].
 ///
 /// Used by [RenderObject.visitChildren] and [RenderObject.visitChildrenForSemantics].
+///
+/// The `child` argument must not be null.
 typedef RenderObjectVisitor = void Function(RenderObject child);
 
 /// Signature for a function that is called during layout.
@@ -1804,6 +1811,10 @@ abstract class RenderObject extends AbstractNode with DiagnosticableTreeMixin im
   /// Typically, subclasses will always return the same value. If the value can
   /// change, then, when it does change, the subclass should make sure to call
   /// [markNeedsLayoutForSizedByParentChange].
+  ///
+  /// Subclasses that return true must not change the dimensions of this render
+  /// object in [performLayout]. Instead, that work should be done by
+  /// [performResize].
   @protected
   bool get sizedByParent => false;
 

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

@@ -71,12 +71,12 @@ class RelativeRect {
 
   /// Distance from the right side of the container to the right side of this rectangle.
   ///
-  /// May be negative if the right side of the rectangle is outside of the container.
+  /// May be positive if the right side of the rectangle is outside of the container.
   final double right;
 
   /// Distance from the bottom side of the container to the bottom side of this rectangle.
   ///
-  /// May be negative if the bottom side of the rectangle is outside of the container.
+  /// May be positive if the bottom side of the rectangle is outside of the container.
   final double bottom;
 
   /// Returns whether any of the values are greater than zero.

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

@@ -93,6 +93,11 @@ class IntrinsicColumnWidth extends TableColumnWidth {
   /// Creates a column width based on intrinsic sizing.
   ///
   /// This sizing algorithm is very expensive.
+  ///
+  /// The `flex` argument specifies the flex factor to apply to the column if
+  /// there is any room left over when laying out the table. If `flex` is
+  /// null (the default), the table will not distribute any extra space to the
+  /// column.
   const IntrinsicColumnWidth({ double flex }) : _flex = flex;
 
   @override

packages/flutter/lib/src/services/text_input.dart

@@ -1000,7 +1000,11 @@ RawFloatingCursorPoint _toTextPoint(FloatingCursorDragState state, Map<String, d
   return RawFloatingCursorPoint(offset: offset, state: state);
 }
 
-/// An interface to the system's text input control.
+/// An low-level interface to the system's text input control.
+///
+/// See also:
+///
+///  * [TextField], a widget in which the user may enter text.
 class TextInput {
   TextInput._() {
     _channel = SystemChannels.textInput;

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

@@ -5801,6 +5801,11 @@ class Listener extends StatelessWidget {
   final PointerCancelEventListener onPointerCancel;
 
   /// Called when a pointer signal occurs over this object.
+  ///
+  /// See also:
+  ///
+  ///  * [PointerSignalEvent], which goes into more detail on pointer signal
+  ///    events.
   final PointerSignalEventListener onPointerSignal;
 
   /// How to behave during hit testing.
@@ -5975,7 +5980,7 @@ class _PointerListener extends SingleChildRenderObjectWidget {
 /// See also:
 ///
 ///  * [Listener], a similar widget that tracks pointer events when the pointer
-///    have buttons pressed.
+///    has buttons pressed.
 class MouseRegion extends StatefulWidget {
   /// Creates a widget that forwards mouse events to callbacks.
   ///

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

@@ -3179,6 +3179,8 @@ abstract class Element extends DiagnosticableTree implements BuildContext {
   /// This method is the core of the widgets system. It is called each time we
   /// are to add, update, or remove a child based on an updated configuration.
   ///
+  /// The `newSlot` argument specifies the new value for this element's [slot].
+  ///
   /// If the `child` is null, and the `newWidget` is not null, then we have a new
   /// child for which we need to create an [Element], configured with `newWidget`.
   ///
@@ -3280,6 +3282,10 @@ abstract class Element extends DiagnosticableTree implements BuildContext {
   ///
   /// This method transitions the element from the "initial" lifecycle state to
   /// the "active" lifecycle state.
+  ///
+  /// Subclasses that override this method are likely to want to also override
+  /// [update], [visitChildren], [insertChildRenderObject], [moveChildRenderObject],
+  /// and [removeChildRenderObject].
   @mustCallSuper
   void mount(Element parent, dynamic newSlot) {
     assert(_debugLifecycleState == _ElementLifecycle.initial);
@@ -3309,6 +3315,7 @@ abstract class Element extends DiagnosticableTree implements BuildContext {
   void _debugRemoveGlobalKeyReservation(Element child) {
     GlobalKey._debugRemoveReservationFor(this, child);
   }
+
   /// Change the widget used to configure this element.
   ///
   /// The framework calls this function when the parent wishes to use a
@@ -3380,7 +3387,7 @@ abstract class Element extends DiagnosticableTree implements BuildContext {
   /// Remove [renderObject] from the render tree.
   ///
   /// The default implementation of this function simply calls
-  /// [detachRenderObject] recursively on its child. The
+  /// [detachRenderObject] recursively on each child. The
   /// [RenderObjectElement.detachRenderObject] override does the actual work of
   /// removing [renderObject] from the render tree.
   ///
@@ -3392,12 +3399,14 @@ abstract class Element extends DiagnosticableTree implements BuildContext {
     _slot = null;
   }
 
-  /// Add [renderObject] to the render tree at the location specified by [slot].
+  /// Add [renderObject] to the render tree at the location specified by `newSlot`.
   ///
   /// The default implementation of this function simply calls
-  /// [attachRenderObject] recursively on its child. The
+  /// [attachRenderObject] recursively on each child. The
   /// [RenderObjectElement.attachRenderObject] override does the actual work of
   /// adding [renderObject] to the render tree.
+  ///
+  /// The `newSlot` argument specifies the new value for this element's [slot].
   void attachRenderObject(dynamic newSlot) {
     assert(_slot == null);
     visitChildren((Element child) {
@@ -3462,6 +3471,8 @@ abstract class Element extends DiagnosticableTree implements BuildContext {
   /// (potentially grafting it from another location in the tree or reactivating
   /// it from the list of inactive elements) rather than creating a new element.
   ///
+  /// The `newSlot` argument specifies the new value for this element's [slot].
+  ///
   /// The element returned by this function will already have been mounted and
   /// will be in the "active" lifecycle state.
   @protected

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

@@ -197,6 +197,12 @@ class GestureRecognizerFactoryWithHandlers<T extends GestureRecognizer> extends
 ///
 /// To see how large the hit test box of a [GestureDetector] is for debugging
 /// purposes, set [debugPaintPointersEnabled] to true.
+///
+/// See also:
+///
+///  * [Listener], a widget for listening to lower-level raw pointer events.
+///  * [MouseRegion], a widget that tracks the movement of mice, even when no
+///    button is pressed.
 class GestureDetector extends StatelessWidget {
   /// Creates a widget that detects gestures.
   ///

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

@@ -968,6 +968,12 @@ abstract class BoxScrollView extends ScrollView {
 /// ```
 /// {@end-tool}
 ///
+/// ## Selection of list items
+///
+/// `ListView` has no built-in notion of a selected item or items. For a small
+/// example of how a caller might wire up basic item selection, see
+/// [ListTile.selected].
+///
 /// See also:
 ///
 ///  * [SingleChildScrollView], which is a scrollable widget that has a single

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

@@ -802,6 +802,8 @@ abstract class SliverMultiBoxAdaptorWidget extends SliverWithKeepAliveWidget {
 ///
 /// See also:
 ///
+///  * <https://flutter.dev/docs/development/ui/advanced/slivers>, a description
+///    of what slivers are and how to use them.
 ///  * [SliverFixedExtentList], which is more efficient for children with
 ///    the same extent in the main axis.
 ///  * [SliverPrototypeExtentList], which is similar to [SliverFixedExtentList]

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

@@ -181,6 +181,8 @@ class Table extends RenderObjectWidget {
   /// sizing algorithms are used here. In particular, [IntrinsicColumnWidth] is
   /// quite expensive because it needs to measure each cell in the column to
   /// determine the intrinsic size of the column.
+  ///
+  /// The keys of this map (column indexes) are zero-based.
   final Map<int, TableColumnWidth> columnWidths;
 
   /// How to determine with widths of columns that don't have an explicit sizing algorithm.
@@ -198,6 +200,9 @@ class Table extends RenderObjectWidget {
   final TableBorder border;
 
   /// How cells that do not explicitly specify a vertical alignment are aligned vertically.
+  ///
+  /// Cells may specify a vertical alignment by wrapping their contents in a
+  /// [TableCell] widget.
   final TableCellVerticalAlignment defaultVerticalAlignment;
 
   /// The text baseline to use when aligning rows using [TableCellVerticalAlignment.baseline].

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

@@ -457,6 +457,8 @@ class Text extends StatelessWidget {
   final bool softWrap;
 
   /// How visual overflow should be handled.
+  ///
+  /// Defaults to retrieving the value from the nearest [DefaultTextStyle] ancestor.
   final TextOverflow overflow;
 
   /// The number of font pixels for each logical pixel.