More Block doc improvements (#6481)

Mostly around pointing people towards Block more aggressively.

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

@@ -48,9 +48,13 @@ Map<MaterialListType, double> kListItemExtent = const <MaterialListType, double>
 ///
 /// See also:
 ///
-///  * [ListItem]
-///  * [ScrollableList]
-///  * [TwoLevelList]
+///  * [Block], which shows heterogeneous widgets in a list and makes the list
+///    scrollable if necessary.
+///  * [ListItem], to show content in a [MaterialList] using material design
+///    conventions.
+///  * [ScrollableList], on which this widget is based.
+///  * [TwoLevelList], for lists that have subsections that can collapse and
+///    expand.
 ///  * [ScrollableGrid]
 ///  * <https://material.google.com/components/lists.html>
 class MaterialList extends StatelessWidget {

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

@@ -255,6 +255,7 @@ class _TwoLevelSublistState extends State<TwoLevelSublist> with SingleTickerProv
 ///
 ///  * [TwoLevelSublist]
 ///  * [TwoLevelListItem]
+///  * [MaterialList], for lists that only have one level.
 class TwoLevelList extends StatelessWidget {
   /// Creates a scrollable list of items that can expand and collapse.
   ///

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

@@ -1406,7 +1406,7 @@ class Viewport extends SingleChildRenderObjectWidget {
 ///
 /// See also:
 ///
-///  * [Block] (which combines block layout with scrolling)
+///  * [Block], which combines block layout with scrolling.
 class BlockBody extends MultiChildRenderObjectWidget {
   /// Creates a block layout widget.
   ///
@@ -1951,6 +1951,13 @@ class Flex extends MultiChildRenderObjectWidget {
 ///
 /// For details about the flex layout algorithm, see [RenderFlex]. To control
 /// the flex of child widgets, see the [Flexible] widget.
+///
+/// The Row widget does not scroll (and in general it is considered an error to
+/// have more children in a Row than will fit in the available room). If you
+/// have a line of widgets and want them to be able to scroll if there is
+/// insufficient room, consider using a [Block].
+///
+/// For a vertical variant, see [Column].
 class Row extends Flex {
   /// Creates a horizontal array of children.
   ///
@@ -1984,6 +1991,8 @@ class Row extends Flex {
 /// to have more children in a Column than will fit in the available room). If
 /// you have a list of widgets and want them to be able to scroll if there is
 /// insufficient room, consider using a [Block].
+///
+/// For a horizontal variant, see [Row].
 class Column extends Flex {
   /// Creates a vertical array of children.
   ///

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

@@ -191,9 +191,13 @@ class LazyBlockChildren extends LazyBlockDelegate {
 /// [scrollOffset] is expensive because [LazyBlock] computes the size of every
 /// child between the old scroll offset and the new scroll offset.
 ///
-/// Prefer [ScrollableList] when all the children have the same size because
+/// Prefer [ScrollableLazyList] when all the children have the same size because
 /// it can use that property to be more efficient. Prefer [ScrollableViewport]
 /// when there is only one child.
+///
+/// Consider [Block] if you have a small number of children that will only
+/// scroll in unusual circumstances (e.g. when the user's device is smaller than
+/// expected).
 class LazyBlock extends StatelessWidget {
   /// Creates an infinite scrolling list of variable height children.
   ///

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

@@ -61,14 +61,14 @@ typedef double SnapOffsetCallback(double scrollOffset, Size containerSize);
 
 /// A base class for scrollable widgets.
 ///
+/// If you have a list of widgets and want them to be able to scroll if there is
+/// insufficient room, consider using [Block].
+///
 /// Commonly used classes that are based on Scrollable include [ScrollableList],
 /// [ScrollableGrid], and [ScrollableViewport].
 ///
 /// Widgets that subclass [Scrollable] typically use state objects that subclass
 /// [ScrollableState].
-///
-/// If you have a list of widgets and want them to be able to scroll if there is
-/// insufficient room, consider using [Block].
 class Scrollable extends StatefulWidget {
   /// Initializes fields for subclasses.
   ///
@@ -916,11 +916,11 @@ class ScrollNotification extends Notification {
 ///
 /// See also:
 ///
+///  * [Block], if your single child is a [Column].
 ///  * [ScrollableList], if you have many identically-sized children.
 ///  * [PageableList], if you have children that each take the entire screen.
 ///  * [ScrollableGrid], if your children are in a grid pattern.
 ///  * [LazyBlock], if you have many children of varying sizes.
-///  * [Block], if your single child is a [BlockBody] or a [Column].
 class ScrollableViewport extends StatelessWidget {
   /// Creates a simple scrolling widget that has a single child.
   ///
@@ -1050,9 +1050,9 @@ class ScrollableViewport extends StatelessWidget {
 ///
 /// See also:
 ///
-///  * [ScrollableViewport], if you only have one child.
+///  * [LazyBlock], if you have many children with varying heights.
 ///  * [ScrollableList], if all your children are the same height.
-///  * [LazyBlock], if you have children with varying heights.
+///  * [ScrollableViewport], if you only have one child.
 class Block extends StatelessWidget {
   /// Creates a scrollable array of children.
   Block({

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

@@ -18,14 +18,16 @@ import 'virtual_viewport.dart';
 /// uses an [Iterable] list of children. That makes [ScrollableList] suitable
 /// for a large (but not extremely large or infinite) list of children.
 ///
-/// [ScrollableList] differs from [LazyBlock] in that [ScrollableList] requires
-/// each of its children to be the same size. That makes [ScrollableList] more
-/// efficient but less flexible than [LazyBlock].
+/// [ScrollableList] differs from [Block] and [LazyBlock] in that
+/// [ScrollableList] requires each of its children to be the same size. That
+/// makes [ScrollableList] more efficient but less flexible than [Block] and
+/// [LazyBlock].
 ///
 /// Prefer [ScrollableViewport] when there is only one child.
 ///
 /// See also:
 ///
+///  * [Block].
 ///  * [ScrollableLazyList].
 ///  * [LazyBlock].
 ///  * [ScrollableViewport].