Explain when and why to use CrossAxisAlignment.baseline (flutter#143632)

Improves the docs around horizontal alignment of text, due to several issues expressing confusion about this topic.

Author: gnprice

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

@@ -142,6 +142,8 @@ enum MainAxisAlignment {
 /// See also:
 ///
 ///  * [Column], [Row], and [Flex], the flex widgets.
+///  * [Flex.crossAxisAlignment], the property on flex widgets that
+///    has this type.
 ///  * [RenderFlex], the flex render object.
 enum CrossAxisAlignment {
   /// Place the children with their start edge aligned with the start side of
@@ -185,16 +187,35 @@ enum CrossAxisAlignment {
 
   /// Place the children along the cross axis such that their baselines match.
   ///
+  /// Consider using this value for any horizontal main axis (as with [Row])
+  /// where the children primarily contain text.  If the different children
+  /// have text with different font metrics (for example because they differ
+  /// in [TextStyle.fontSize] or other [TextStyle] properties, or because
+  /// they use different fonts due to being written in different scripts),
+  /// then this typically produces better visual alignment than the other
+  /// [CrossAxisAlignment] values, which use no information about
+  /// where the text sits vertically within its bounding box.
+  ///
+  /// The baseline of a widget is typically the typographic baseline of the
+  /// first text in the first [Text] or [RichText] widget it encloses, if any.
+  /// The typographic baseline is a horizontal line used for aligning text,
+  /// which is specified by each font; for alphabetic scripts, it ordinarily
+  /// runs along the bottom of letters excluding any descenders.
+  ///
   /// 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].
+  /// horizontal main axes (as with [Row]). If the main axis is vertical
+  /// (as with [Column]), 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.
+  ///
+  /// See also:
+  ///
+  ///  * [RenderBox.getDistanceToBaseline], which defines the baseline of a box.
   baseline,
 }
 

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

@@ -4629,6 +4629,13 @@ class Flex extends MultiChildRenderObjectWidget {
   ///
   /// For example, [CrossAxisAlignment.center], the default, centers the
   /// children in the cross axis (e.g., horizontally for a [Column]).
+  ///
+  /// When the cross axis is vertical (as for a [Row]) and the children
+  /// contain text, consider using [CrossAxisAlignment.baseline] instead.
+  /// This typically produces better visual results if the different children
+  /// have text with different font metrics, for example because they differ in
+  /// [TextStyle.fontSize] or other [TextStyle] properties, or because
+  /// they use different fonts due to being written in different scripts.
   final CrossAxisAlignment crossAxisAlignment;
 
   /// Determines the order to lay children out horizontally and how to interpret
@@ -4778,6 +4785,14 @@ class Flex extends MultiChildRenderObjectWidget {
 /// If you only have one child, then consider using [Align] or [Center] to
 /// position the child.
 ///
+/// By default, [crossAxisAlignment] is [CrossAxisAlignment.center], which
+/// centers the children in the vertical axis.  If several of the children
+/// contain text, this is likely to make them visually misaligned if
+/// they have different font metrics (for example because they differ in
+/// [TextStyle.fontSize] or other [TextStyle] properties, or because
+/// they use different fonts due to being written in different scripts).
+/// Consider using [CrossAxisAlignment.baseline] instead.
+///
 /// {@tool snippet}
 ///
 /// This example divides the available space into three (horizontally), and