Update TextStyle and StrutStyle height docs (#33281)

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

@@ -8,19 +8,21 @@ import 'basic_types.dart';
 import 'text_style.dart';
 
 /// Defines the strut, which sets the minimum height a line can be
-/// relative to the baseline. Strut applies to all lines in the paragraph.
-///
-/// Strut is a feature that allows minimum line heights to be set. The effect is as
-/// if a zero width space was included at the beginning of each line in the
-/// paragraph. This imaginary space is 'shaped' according the properties defined
-/// in this class. Flutter's strut is based on [typesetting strut](https://en.wikipedia.org/wiki/Strut_(typesetting))
+/// relative to the baseline.
+///
+/// Strut applies to all lines in the paragraph. Strut is a feature that
+/// allows minimum line heights to be set. The effect is as if a zero
+/// width space was included at the beginning of each line in the
+/// paragraph. This imaginary space is 'shaped' according the properties
+/// defined in this class. Flutter's strut is based on
+/// [typesetting strut](https://en.wikipedia.org/wiki/Strut_(typesetting))
 /// and CSS's [line-height](https://www.w3.org/TR/CSS2/visudet.html#line-height).
 ///
-/// No lines may be shorter than the strut. The ascent and descent of the strut
-/// are calculated, and any laid out text that has a shorter ascent or descent than
-/// the strut's ascent or descent will take the ascent and descent of the strut.
-/// Text with ascents or descents larger than the strut's ascent or descent will lay
-/// out as normal and extend past the strut.
+/// No lines may be shorter than the strut. The ascent and descent of the
+/// strut are calculated, and any laid out text that has a shorter ascent or
+/// descent than the strut's ascent or descent will take the ascent and
+/// descent of the strut. Text with ascents or descents larger than the
+/// strut's ascent or descent will layout as normal and extend past the strut.
 ///
 /// Strut is defined independently from any text content or [TextStyle]s.
 ///
@@ -33,16 +35,26 @@ import 'text_style.dart';
 ///
 /// The sum of these four values is the total height of the line.
 ///
-/// The `ascent + descent` is equivalent to the [fontSize]. Ascent is the font's
-/// spacing above the baseline without leading and descent is the spacing below the
-/// baseline without leading. Leading is split evenly between the top and bottom.
-/// The values for `ascent` and `descent` are provided by the font named by
-/// [fontFamily]. If no [fontFamily] or [fontFamilyFallback] is provided, then the
-/// platform's default family will be used.
+/// Ascent is the font's spacing above the baseline without leading and
+/// descent is the spacing below the baseline without leading. Leading is
+/// split evenly betweenthe top and bottom. The values for `ascent` and
+/// `descent` are provided by the font named by [fontFamily]. If no
+/// [fontFamily] or [fontFamilyFallback] is provided, then the platform's
+/// default family will be used.
+///
+/// When [height] is omitted or null, then the font defined ascent and descent
+/// will be used. The font's combined ascent and descent may be taller or
+/// shorter than the [fontSize]. When [height] is provided, the line's EM-square
+/// ascent and descent (which sums to [fontSize]) will be scaled by [height] to
+/// achieve a final line height of `fontSize * height + fontSize * leading`
+/// logical pixels. The proportion of ascent:descent with [height] specified
+/// is the same as the font metrics defined ascent:descent ratio.
+///
+/// ![Text height diagram](https://flutter.github.io/assets-for-api-docs/assets/painting/text_height_diagram.png)
 ///
-/// Each line's spacing above the baseline will be at least as tall as the half
-/// leading plus ascent. Each line's spacing below the baseline will be at least as
-/// tall as the half leading plus descent.
+/// Each line's spacing above the baseline will be at least as tall as the
+/// half leading plus ascent. Each line's spacing below the baseline will
+/// be at least as tall as the half leading plus descent.
 ///
 /// See also:
 ///
@@ -65,47 +77,55 @@ import 'text_style.dart';
 ///    (e.g., Roboto). No glyphs from the font will be drawn and the font will
 ///    be used purely for metrics.
 ///
-///  * [fontFamilyFallback]: an ordered list of font family names that will be searched for when
-///    the font in [fontFamily] cannot be found. When all specified font families have been
-///    exhausted an no match was found, the default platform font will be used.
+///  * [fontFamilyFallback]: an ordered list of font family names that will
+///    be searched for when the font in [fontFamily] cannot be found. When
+///    all specified font families have been exhausted an no match was found,
+///    the default platform font will be used.
 ///
 ///  * [fontSize]: the size of the ascent plus descent in logical pixels. This
 ///    is also used as the basis of the custom leading calculation. This value
 ///    cannot be negative.
 ///    Default is 14 logical pixels.
 ///
-///  * [height]: the multiple of [fontSize] to multiply the ascent and descent by.
-///    The [height] will impact the spacing above and below the baseline differently
-///    depending on the ratios between the font's ascent and descent. This property is
-///    separate from the leading multiplier, which is controlled through [leading].
-///    Default is 1.0.
-///
-///  * [leading]: the custom leading to apply to the strut as a multiple of [fontSize].
-///    Leading is additional spacing between lines. Half of the leading is added
-///    to the top and the other half to the bottom of the line height. This differs
-///    from [height] since the spacing is equally distributed above and below the
-///    baseline.
-///    Default is `null`, which will use the font-specified leading.
-///
-///  * [fontWeight]: the typeface thickness to use when calculating the strut (e.g., bold).
+///  * [height]: the multiple of [fontSize] the line's height should be.
+///    The line's height will take the font's ascent and descent values if
+///    [height] is omitted or null. If provided, the EM-square ascent and
+///    descent (which sum to [fontSize]) is scaled by [height].
+///    The [height] will impact the spacing above and below the baseline
+///    differently depending on the ratios between the font's ascent and
+///    descent. This property is separate from the leading multiplier, which
+///    is controlled through [leading].
+///    Default is null.
+///
+///  * [leading]: the custom leading to apply to the strut as a multiple of
+///    [fontSize]. Leading is additional spacing between lines. Half of the
+///    leading is added to the top and the other half to the bottom of the
+///    line height. This differs from [height] since the spacing is equally
+///    distributed above and below the baseline.
+///    Default is null, which will use the font-specified leading.
+///
+///  * [fontWeight]: the typeface thickness to use when calculating the strut
+///    (e.g., bold).
 ///    Default is [FontWeight.w400].
 ///
-///  * [fontStyle]: the typeface variant to use when calculating the strut (e.g., italic).
+///  * [fontStyle]: the typeface variant to use when calculating the strut
+///    (e.g., italic).
 ///    Default is [FontStyle.normal].
 ///
-///  * [forceStrutHeight]: when true, all lines will be laid out with the height of the
-///    strut. All line and run-specific metrics will be ignored/overridden and only strut
-///    metrics will be used instead. This property guarantees uniform line spacing, however
-///    text in adjacent lines may overlap. This property should be enabled with caution as
-///    it bypasses a large portion of the vertical layout system.
+///  * [forceStrutHeight]: when true, all lines will be laid out with the
+///    height of the strut. All line and run-specific metrics will be
+///    ignored/overridden and only strut metrics will be used instead.
+///    This property guarantees uniform line spacing, however text in
+///    adjacent lines may overlap. This property should be enabled with
+///    caution as it bypasses a large portion of the vertical layout system.
 ///    The default value is false.
 ///
 /// ### Examples
 ///
 /// {@tool sample}
-/// In this simple case, the text will be rendered at font size 10, however, the vertical
-/// height of each line will be the strut height (Roboto in font size 30 * 1.5) as the text
-/// itself is shorter than the strut.
+/// In this simple case, the text will be rendered at font size 10, however,
+/// the vertical height of each line will be the strut height (Roboto in
+/// font size 30 * 1.5) as the text itself is shorter than the strut.
 ///
 /// ```dart
 /// const Text(
@@ -271,7 +291,8 @@ class StrutStyle extends Diagnosticable {
   /// package. It is combined with the `fontFamily` argument to set the
   /// [fontFamily] property.
   ///
-  /// If provided, fontSize must be positive and non-zero, leading must be zero or positive.
+  /// If provided, fontSize must be positive and non-zero, leading must be
+  /// zero or positive.
   const StrutStyle({
     String fontFamily,
     List<String> fontFamilyFallback,
@@ -296,16 +317,19 @@ class StrutStyle extends Diagnosticable {
   /// The [textStyle] parameter must not be null.
   ///
   /// The named parameters override the [textStyle]'s argument's properties.
-  /// Since TextStyle does not contain [leading] or [forceStrutHeight], these values
-  /// will take on default values (null and false) unless otherwise specified.
+  /// Since TextStyle does not contain [leading] or [forceStrutHeight], these
+  /// values will take on default values (null and false) unless otherwise
+  /// specified.
   ///
-  /// If provided, fontSize must be positive and non-zero, leading must be zero or positive.
+  /// If provided, fontSize must be positive and non-zero, leading must be
+  /// zero or positive.
   ///
-  /// When [textStyle] has a package and a new [package] is also specified, the entire
-  /// font family fallback list should be redefined since the [textStyle]'s package data
-  /// is inherited by being prepended onto the font family names. If
-  /// [fontFamilyFallback] is meant to be empty, pass an empty list instead of null.
-  /// This prevents the previous package name from being prepended twice.
+  /// When [textStyle] has a package and a new [package] is also specified,
+  /// the entire font family fallback list should be redefined since the
+  /// [textStyle]'s package data is inherited by being prepended onto the
+  /// font family names. If [fontFamilyFallback] is meant to be empty, pass
+  /// an empty list instead of null. This prevents the previous package name
+  /// from being prepended twice.
   StrutStyle.fromTextStyle(
     TextStyle textStyle, {
     String fontFamily,
@@ -329,8 +353,8 @@ class StrutStyle extends Diagnosticable {
        fontWeight = fontWeight ?? textStyle.fontWeight,
        fontStyle = fontStyle ?? textStyle.fontStyle,
        debugLabel = debugLabel ?? textStyle.debugLabel,
-       _package = package; // the textStyle._package data is embedded in the fontFamily names,
-                           // so we no longer need it.
+       _package = package; // the textStyle._package data is embedded in the
+                           // fontFamily names, so we no longer need it.
 
   /// A [StrutStyle] that will have no impact on the text layout.
   ///
@@ -394,15 +418,32 @@ class StrutStyle extends Diagnosticable {
   /// The default fontSize is 14 logical pixels.
   final double fontSize;
 
-  /// The multiple of [fontSize] to multiply the ascent and descent by where `ascent + descent = fontSize`.
+  /// The multiple of [fontSize] to multiply the ascent and descent by where
+  /// `ascent + descent = fontSize`.
   ///
-  /// Ascent is the spacing above the baseline and descent is the spacing below the baseline.
+  /// Ascent is the spacing above the baseline and descent is the spacing below
+  /// the baseline.
+  ///
+  /// When [height] is omitted or null, then the font defined ascent and descent
+  /// will be used. The font's combined ascent and descent may be taller or
+  /// shorter than the [fontSize]. When [height] is provided, the line's EM-square
+  /// ascent and descent (which sums to [fontSize]) will be scaled by [height] to
+  /// achieve a final line height of `fontSize * height + fontSize * leading`
+  /// logical pixels. The following diagram illustrates the differences between
+  /// the font metrics defined height and the EM-square height:
+  ///
+  /// ![Text height diagram](https://flutter.github.io/assets-for-api-docs/assets/painting/text_height_diagram.png)
   ///
   /// The [height] will impact the spacing above and below the baseline differently
   /// depending on the ratios between the font's ascent and descent. This property is
   /// separate from the leading multiplier, which is controlled through [leading].
   ///
-  /// The default height is 1.0.
+  /// The ratio of ascent:descent with [height] specified is the same as the
+  /// font metrics defined ascent:descent ratio when [height] is null or omitted.
+  ///
+  /// See [TextStyle.height], which works in a similar manner.
+  ///
+  /// The default height is null.
   final double height;
 
   /// The typeface thickness to use when calculating the strut (e.g., bold).
@@ -428,9 +469,9 @@ class StrutStyle extends Diagnosticable {
   /// Whether the strut height should be forced.
   ///
   /// When true, all lines will be laid out with the height of the
-  /// strut. All line and run-specific metrics will be ignored/overridden and only strut
-  /// metrics will be used instead. This property guarantees uniform line spacing, however
-  /// text in adjacent lines may overlap.
+  /// strut. All line and run-specific metrics will be ignored/overridden
+  /// and only strut metrics will be used instead. This property guarantees
+  /// uniform line spacing, however text in adjacent lines may overlap.
   ///
   /// This property should be enabled with caution as
   /// it bypasses a large portion of the vertical layout system.
@@ -473,12 +514,12 @@ class StrutStyle extends Diagnosticable {
     return RenderComparison.identical;
   }
 
-  /// Returns a new strut style that inherits its null values from corresponding
-  /// properties in the [other] [TextStyle].
+  /// Returns a new strut style that inherits its null values from
+  /// corresponding properties in the [other] [TextStyle].
   ///
-  /// The "missing" properties of the this strut style are _filled_ by the properties
-  /// of the provided [TextStyle]. This is possible because [StrutStyle] shares many of
-  /// the same basic properties as [TextStyle].
+  /// The "missing" properties of the this strut style are _filled_ by
+  /// the properties of the provided [TextStyle]. This is possible because
+  /// [StrutStyle] shares many of the same basic properties as [TextStyle].
   ///
   /// If the given text style is null, returns this strut style.
   StrutStyle inheritFromTextStyle(TextStyle other) {

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

@@ -106,18 +106,38 @@ const String _kColorBackgroundWarning = 'Cannot provide both a backgroundColor a
 ///
 /// ### Line height
 ///
+/// By default, text will layout with line height as defined by the font.
+/// Font-metrics defined line height may be taller or shorter than the font size.
+/// The [height] property allows manual adjustment of the height of the line as
+/// a multiple of [fontSize]. For most fonts, setting [height] to 1.0 is not
+/// the same as omitting or setting height to null. The following diagram
+/// illustrates the difference between the font-metrics defined line height and
+/// the line height produced with `height: 1.0` (also known as the EM-square):
+///
+/// ![Text height diagram](https://flutter.github.io/assets-for-api-docs/assets/painting/text_height_diagram.png)
+///
 /// {@tool sample}
 /// The [height] property can be used to change the line height. Here, the line
 /// height is set to 5 times the font size, so that the text is very spaced out.
+/// Since the `fontSize` is set to 10, the final height of the line is
+/// 50 pixels.
 ///
 /// ```dart
 /// Text(
 ///   'Don\'t act surprised, you guys, cuz I wrote \'em!',
-///   style: TextStyle(height: 5.0),
+///   style: TextStyle(fontSize: 10, height: 5.0),
 /// )
 /// ```
 /// {@end-tool}
 ///
+/// {@tool sample}
+///
+/// Examples of the resulting heights from different values of `TextStyle.height`:
+///
+/// ![Text height comparison diagram](https://flutter.github.io/assets-for-api-docs/assets/painting/text_height_comparison_diagram.png)
+///
+/// {@end-tool}
+///
 /// ### Wavy red underline with black text
 ///
 /// {@tool sample}
@@ -439,9 +459,28 @@ class TextStyle extends Diagnosticable {
 
   /// The height of this text span, as a multiple of the font size.
   ///
-  /// If applied to the root [TextSpan], this value sets the line height, which
-  /// is the minimum distance between subsequent text baselines, as multiple of
-  /// the font size.
+  /// When [height] is null or omitted, the line height will be determined
+  /// by the font's metrics directly, which may differ from the fontSize.
+  /// When [height] is non-null, the line height of the span of text will be a
+  /// multiple of [fontSize] and be exactly `fontSize * height` logical pixels
+  /// tall.
+  ///
+  /// For most fonts, setting [height] to 1.0 is not the same as omitting or
+  /// setting height to null because the [fontSize] sets the height of the EM-square,
+  /// which is different than the font provided metrics for line height. The
+  /// following diagram illustrates the difference between the font-metrics
+  /// defined line height and the line height produced with `height: 1.0`
+  /// (which forms the upper and lower edges of the EM-square):
+  ///
+  /// ![Text height diagram](https://flutter.github.io/assets-for-api-docs/assets/painting/text_height_diagram.png)
+  ///
+  /// {@tool sample}
+  ///
+  /// Examples of the resulting line heights from different values of `TextStyle.height`:
+  ///
+  /// ![Text height comparison diagram](https://flutter.github.io/assets-for-api-docs/assets/painting/text_height_comparison_diagram.png)
+  ///
+  /// {@end-tool}
   final double height;
 
   /// The locale used to select region-specific glyphs.