assert(elevation >= 0.0) and doc clarifications (#25345)

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

@@ -131,7 +131,8 @@ class AppBar extends StatefulWidget implements PreferredSizeWidget {
   /// Creates a material design app bar.
   ///
   /// The arguments [elevation], [primary], [toolbarOpacity], [bottomOpacity]
-  /// and [automaticallyImplyLeading] must not be null.
+  /// and [automaticallyImplyLeading] must not be null. Additionally,
+  /// [elevation] must be non-negative.
   ///
   /// Typically used in the [Scaffold.appBar] property.
   AppBar({
@@ -153,7 +154,7 @@ class AppBar extends StatefulWidget implements PreferredSizeWidget {
     this.toolbarOpacity = 1.0,
     this.bottomOpacity = 1.0,
   }) : assert(automaticallyImplyLeading != null),
-       assert(elevation != null),
+       assert(elevation != null && elevation >= 0.0),
        assert(primary != null),
        assert(titleSpacing != null),
        assert(toolbarOpacity != null),
@@ -264,10 +265,13 @@ class AppBar extends StatefulWidget implements PreferredSizeWidget {
   ///  * [PreferredSize], which can be used to give an arbitrary widget a preferred size.
   final PreferredSizeWidget bottom;
 
-  /// The z-coordinate at which to place this app bar. This controls the size of
-  /// the shadow below the app bar.
+  /// The z-coordinate at which to place this app bar relative to its parent.
+  ///
+  /// This controls the size of the shadow below the app bar.
   ///
   /// Defaults to 4, the appropriate elevation for app bars.
+  ///
+  /// The value is non-negative.
   final double elevation;
 
   /// The color to use for the app bar's material. Typically this should be set

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

@@ -42,6 +42,7 @@ class BottomAppBar extends StatefulWidget {
   /// Creates a bottom application bar.
   ///
   /// The [color], [elevation], and [clipBehavior] arguments must not be null.
+  /// Additionally, [elevation] must be non-negative.
   const BottomAppBar({
     Key key,
     this.color,
@@ -68,8 +69,11 @@ class BottomAppBar extends StatefulWidget {
   /// When null defaults to [ThemeData.bottomAppBarColor].
   final Color color;
 
-  /// The z-coordinate at which to place this bottom app bar. This controls the
-  /// size of the shadow below the bottom app bar.
+  /// The z-coordinate at which to place this bottom app bar relative to its
+  /// parent.
+  ///
+  /// This controls the size of the shadow below the bottom app bar. The
+  /// value is non-negative.
   ///
   /// Defaults to 8, the appropriate elevation for bottom app bars.
   final double elevation;

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

@@ -59,7 +59,7 @@ class BottomSheet extends StatefulWidget {
   }) : assert(enableDrag != null),
        assert(onClosing != null),
        assert(builder != null),
-       assert(elevation != null),
+       assert(elevation != null && elevation >= 0.0),
        super(key: key);
 
   /// The animation that controls the bottom sheet's position.
@@ -87,10 +87,11 @@ class BottomSheet extends StatefulWidget {
   /// Default is true.
   final bool enableDrag;
 
-  /// The z-coordinate at which to place this material. This controls the size
-  /// of the shadow below the material.
+  /// The z-coordinate at which to place this material relative to its parent.
   ///
-  /// Defaults to 0.
+  /// This controls the size of the shadow below the material.
+  ///
+  /// Defaults to 0. The value is non-negative.
   final double elevation;
 
   @override

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

@@ -28,8 +28,10 @@ import 'theme_data.dart';
 class RawMaterialButton extends StatefulWidget {
   /// Create a button based on [Semantics], [Material], and [InkWell] widgets.
   ///
-  /// The [shape], [elevation], [padding], [constraints], and [clipBehavior]
-  /// arguments must not be null.
+  /// The [shape], [elevation], [highlightElevation], [disabledElevation],
+  /// [padding], [constraints], and [clipBehavior] arguments must not be null.
+  /// Additionally, [elevation], [highlightElevation], and [disabledElevation]
+  /// must be non-negative.
   const RawMaterialButton({
     Key key,
     @required this.onPressed,
@@ -50,9 +52,9 @@ class RawMaterialButton extends StatefulWidget {
     this.child,
   }) : materialTapTargetSize = materialTapTargetSize ?? MaterialTapTargetSize.padded,
        assert(shape != null),
-       assert(elevation != null),
-       assert(highlightElevation != null),
-       assert(disabledElevation != null),
+       assert(elevation != null && elevation >= 0.0),
+       assert(highlightElevation != null && highlightElevation >= 0.0),
+       assert(disabledElevation != null && disabledElevation >= 0.0),
        assert(padding != null),
        assert(constraints != null),
        assert(animationDuration != null),
@@ -84,7 +86,7 @@ class RawMaterialButton extends StatefulWidget {
   /// The elevation for the button's [Material] when the button
   /// is [enabled] but not pressed.
   ///
-  /// Defaults to 2.0.
+  /// Defaults to 2.0. The value is always non-negative.
   ///
   /// See also:
   ///
@@ -95,7 +97,7 @@ class RawMaterialButton extends StatefulWidget {
   /// The elevation for the button's [Material] when the button
   /// is [enabled] and pressed.
   ///
-  /// Defaults to 8.0.
+  /// Defaults to 8.0. The value is always non-negative.
   ///
   /// See also:
   ///
@@ -106,7 +108,7 @@ class RawMaterialButton extends StatefulWidget {
   /// The elevation for the button's [Material] when the button
   /// is not [enabled].
   ///
-  /// Defaults to 0.0.
+  /// Defaults to 0.0. The value is always non-negative.
   ///
   ///  * [elevation], the default elevation.
   ///  * [highlightElevation], the elevation when the button is pressed.

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

@@ -65,17 +65,19 @@ import 'theme.dart';
 class Card extends StatelessWidget {
   /// Creates a material design card.
   ///
-  /// The [clipBehavior] argument must not be null.
+  /// The [clipBehavior] and [elevation] arguments must not be null.
+  /// Additionally, the [elevation] must be non-negative.
   const Card({
     Key key,
     this.color,
-    this.elevation,
+    this.elevation = 1.0,
     this.shape,
     this.margin = const EdgeInsets.all(4.0),
     this.clipBehavior = Clip.none,
     this.child,
     this.semanticContainer = true,
-  }) : super(key: key);
+  }) : assert(elevation != null && elevation >= 0.0),
+       super(key: key);
 
   /// The card's background color.
   ///
@@ -89,7 +91,7 @@ class Card extends StatelessWidget {
   ///
   /// Defines the card's [Material.elevation].
   ///
-  /// The default elevation is 1.0.
+  /// The default elevation is 1.0. The value is always non-negative.
   final double elevation;
 
   /// The shape of the card's [Material].
@@ -139,7 +141,7 @@ class Card extends StatelessWidget {
         child: Material(
           type: MaterialType.card,
           color: color ?? Theme.of(context).cardColor,
-          elevation: elevation ?? 1.0,
+          elevation: elevation,
           shape: shape ?? const RoundedRectangleBorder(
             borderRadius: BorderRadius.all(Radius.circular(4.0)),
           ),

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

@@ -287,10 +287,12 @@ abstract class SelectableChipAttributes {
   /// {@end-tool}
   ValueChanged<bool> get onSelected;
 
-  /// Elevation to be applied on the chip during the press motion.
+  /// Elevation to be applied on the chip relative to its parent during the
+  /// press motion.
+  ///
   /// This controls the size of the shadow below the chip.
   ///
-  /// Defaults to 8.
+  /// Defaults to 8. The value is always non-negative.
   double get pressElevation;
 
   /// Color to be used for the chip's background, indicating that it is
@@ -397,10 +399,12 @@ abstract class TappableChipAttributes {
   /// {@end-tool}
   VoidCallback get onPressed;
 
-  /// Elevation to be applied on the chip during the press motion.
+  /// Elevation to be applied on the chip relative to its parent during the
+  /// press motion.
+  ///
   /// This controls the size of the shadow below the chip.
   ///
-  /// Defaults to 8.
+  /// Defaults to 8. The value is always non-negative.
   double get pressElevation;
 
   /// Tooltip string to be used for the body area (where the label and avatar
@@ -1159,7 +1163,8 @@ class RawChip extends StatefulWidget
   /// The [onPressed] and [onSelected] callbacks must not both be specified at
   /// the same time.
   ///
-  /// The [label], [isEnabled], and [clipBehavior] arguments must not be null.
+  /// The [label], [pressElevation], [isEnabled], and [clipBehavior] arguments
+  /// must not be null. Additionally, [pressElevation] must be non-negative.
   const RawChip({
     Key key,
     this.avatar,
@@ -1188,6 +1193,7 @@ class RawChip extends StatefulWidget
   })  : assert(label != null),
         assert(isEnabled != null),
         assert(clipBehavior != null),
+        assert(pressElevation != null && pressElevation >= 0.0),
         deleteIcon = deleteIcon ?? _kDefaultDeleteIcon,
         super(key: key);
 

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

@@ -85,17 +85,22 @@ class Drawer extends StatelessWidget {
   /// Creates a material design drawer.
   ///
   /// Typically used in the [Scaffold.drawer] property.
+  ///
+  /// The [elevation] must be non-negative.
   const Drawer({
     Key key,
     this.elevation = 16.0,
     this.child,
     this.semanticLabel,
-  }) : super(key: key);
+  }) : assert(elevation != null && elevation >= 0.0),
+       super(key: key);
 
-  /// The z-coordinate at which to place this drawer. This controls the size of
-  /// the shadow below the drawer.
+  /// The z-coordinate at which to place this drawer relative to its parent.
+  ///
+  /// This controls the size of the shadow below the drawer.
   ///
-  /// Defaults to 16, the appropriate elevation for drawers.
+  /// Defaults to 16, the appropriate elevation for drawers. The value is
+  /// always non-negative.
   final double elevation;
 
   /// The widget below this widget in the tree.

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

@@ -58,7 +58,8 @@ class FloatingActionButton extends StatefulWidget {
   /// Creates a circular floating action button.
   ///
   /// The [elevation], [highlightElevation], [mini], [shape], and [clipBehavior]
-  /// arguments must not be null.
+  /// arguments must not be null. Additionally, [elevation] and
+  /// [highlightElevation] must be non-negative.
   const FloatingActionButton({
     Key key,
     this.child,
@@ -74,8 +75,8 @@ class FloatingActionButton extends StatefulWidget {
     this.clipBehavior = Clip.none,
     this.materialTapTargetSize,
     this.isExtended = false,
-  }) :  assert(elevation != null),
-        assert(highlightElevation != null),
+  }) :  assert(elevation != null && elevation >= 0.0),
+        assert(highlightElevation != null && highlightElevation >= 0.0),
         assert(mini != null),
         assert(shape != null),
         assert(isExtended != null),
@@ -86,7 +87,8 @@ class FloatingActionButton extends StatefulWidget {
   /// an [icon] and a [label].
   ///
   /// The [label], [icon], [elevation], [highlightElevation], [clipBehavior]
-  /// and [shape] arguments must not be null.
+  /// and [shape] arguments must not be null. Additionally, [elevation] and
+  //  [highlightElevation] must be non-negative.
   FloatingActionButton.extended({
     Key key,
     this.tooltip,
@@ -102,8 +104,8 @@ class FloatingActionButton extends StatefulWidget {
     this.clipBehavior = Clip.none,
     @required Widget icon,
     @required Widget label,
-  }) :  assert(elevation != null),
-        assert(highlightElevation != null),
+  }) :  assert(elevation != null && elevation >= 0.0),
+        assert(highlightElevation != null && highlightElevation >= 0.0),
         assert(shape != null),
         assert(isExtended != null),
         assert(clipBehavior != null),
@@ -163,18 +165,22 @@ class FloatingActionButton extends StatefulWidget {
   /// If this is set to null, the button will be disabled.
   final VoidCallback onPressed;
 
-  /// The z-coordinate at which to place this button. This controls the size of
-  /// the shadow below the floating action button.
+  /// The z-coordinate at which to place this button releative to its parent.
   ///
-  /// Defaults to 6, the appropriate elevation for floating action buttons.
+  ///
+  /// This controls the size of the shadow below the floating action button.
+  ///
+  /// Defaults to 6, the appropriate elevation for floating action buttons. The
+  /// value is always non-negative.
   final double elevation;
 
-  /// The z-coordinate at which to place this button when the user is touching
-  /// the button. This controls the size of the shadow below the floating action
-  /// button.
+  /// The z-coordinate at which to place this button relative to its parent when
+  /// the user is touching the button.
+  ///
+  /// This controls the size of the shadow below the floating action button.
   ///
   /// Defaults to 12, the appropriate elevation for floating action buttons
-  /// while they are being touched.
+  /// while they are being touched. The value is always non-negative.
   ///
   /// See also:
   ///

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

@@ -156,7 +156,7 @@ class Material extends StatefulWidget {
   /// Creates a piece of material.
   ///
   /// The [type], [elevation], [shadowColor], and [animationDuration] arguments
-  /// must not be null.
+  /// must not be null. Additionally, [elevation] must be non-negative.
   ///
   /// If a [shape] is specified, then the [borderRadius] property must be
   /// null and the [type] property must not be [MaterialType.circle]. If the
@@ -176,7 +176,7 @@ class Material extends StatefulWidget {
     this.animationDuration = kThemeChangeDuration,
     this.child,
   }) : assert(type != null),
-       assert(elevation != null),
+       assert(elevation != null && elevation >= 0.0),
        assert(shadowColor != null),
        assert(!(shape != null && borderRadius != null)),
        assert(animationDuration != null),
@@ -195,14 +195,17 @@ class Material extends StatefulWidget {
   final MaterialType type;
 
   /// {@template flutter.material.material.elevation}
-  /// The z-coordinate at which to place this material. This controls the size
-  /// of the shadow below the material.
+  /// The z-coordinate at which to place this material relative to its parent.
+  ///
+  /// This controls the size of the shadow below the material.
   ///
   /// If this is non-zero, the contents of the material are clipped, because the
   /// widget conceptually defines an independent printed piece of material.
   ///
   /// Defaults to 0. Changing this value will cause the shadow to animate over
   /// [animationDuration].
+  ///
+  /// The value is non-negative.
   /// {@endtemplate}
   final double elevation;
 
@@ -609,7 +612,7 @@ class _MaterialInterior extends ImplicitlyAnimatedWidget {
   }) : assert(child != null),
        assert(shape != null),
        assert(clipBehavior != null),
-       assert(elevation != null),
+       assert(elevation != null && elevation >= 0.0),
        assert(color != null),
        assert(shadowColor != null),
        super(key: key, curve: curve, duration: duration);
@@ -628,7 +631,10 @@ class _MaterialInterior extends ImplicitlyAnimatedWidget {
   /// {@macro flutter.widgets.Clip}
   final Clip clipBehavior;
 
-  /// The target z-coordinate at which to place this physical object.
+  /// The target z-coordinate at which to place this physical object relative
+  /// to its parent.
+  ///
+  /// The value is non-negative.
   final double elevation;
 
   /// The target background color.

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

@@ -41,8 +41,6 @@ class MaterialButton extends StatelessWidget {
   /// Rather than creating a material button directly, consider using
   /// [FlatButton] or [RaisedButton]. To create a custom Material button
   /// consider using [RawMaterialButton].
-  ///
-  /// The [clipBehavior] argument must not be null.
   const MaterialButton({
     Key key,
     @required this.onPressed,
@@ -150,10 +148,12 @@ class MaterialButton extends StatelessWidget {
   /// the current theme's highlight color, [ThemeData.highlightColor].
   final Color highlightColor;
 
-  /// The z-coordinate at which to place this button. This controls the size of
-  /// the shadow below the raised button.
+  /// The z-coordinate at which to place this button relative to its parent.
+  ///
+  /// This controls the size of the shadow below the raised button.
   ///
-  /// Defaults to 2, the appropriate elevation for raised buttons.
+  /// Defaults to 2, the appropriate elevation for raised buttons. The value
+  /// is always non-negative.
   ///
   /// See also:
   ///
@@ -162,14 +162,14 @@ class MaterialButton extends StatelessWidget {
   ///  * [highlightElevation], the elevation when the button is pressed.
   final double elevation;
 
-  /// The elevation for the button's [Material] when the button
-  /// is [enabled] and pressed.
+  /// The elevation for the button's [Material] relative to its parent when the
+  /// button is [enabled] and pressed.
   ///
   /// This controls the size of the shadow below the button. When a tap
   /// down gesture occurs within the button, its [InkWell] displays a
   /// [highlightColor] "highlight".
   ///
-  /// Defaults to 8.0.
+  /// Defaults to 8.0. The value is always non-negative.
   ///
   /// See also:
   ///
@@ -177,10 +177,10 @@ class MaterialButton extends StatelessWidget {
   ///  * [disabledElevation], the elevation when the button is disabled.
   final double highlightElevation;
 
-  /// The elevation for the button's [Material] when the button
-  /// is not [enabled].
+  /// The elevation for the button's [Material] relative to its parent when the
+  /// button is not [enabled].
   ///
-  /// Defaults to 0.0.
+  /// Defaults to 0.0. The value is always non-negative.
   ///
   /// See also:
   ///

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

@@ -44,7 +44,8 @@ class RaisedButton extends MaterialButton {
   /// Create a filled button.
   ///
   /// The [elevation], [highlightElevation], [disabledElevation], and
-  /// [clipBehavior] arguments must not be null.
+  /// [clipBehavior] arguments must not be null. Additionally,  [elevation],
+  /// [highlightElevation], and [disabledElevation] must be non-negative.
   const RaisedButton({
     Key key,
     @required VoidCallback onPressed,

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

@@ -1504,6 +1504,7 @@ class RenderClipPath extends _RenderCustomClip<Path> {
 /// determine the actual shape of the physical model.
 abstract class _RenderPhysicalModelBase<T> extends _RenderCustomClip<T> {
   /// The [shape], [elevation], [color], and [shadowColor] must not be null.
+  /// Additionally, the [elevation] must be non-negative.
   _RenderPhysicalModelBase({
     @required RenderBox child,
     @required double elevation,
@@ -1511,7 +1512,7 @@ abstract class _RenderPhysicalModelBase<T> extends _RenderCustomClip<T> {
     @required Color shadowColor,
     Clip clipBehavior = Clip.none,
     CustomClipper<T> clipper,
-  }) : assert(elevation != null),
+  }) : assert(elevation != null && elevation >= 0.0),
        assert(color != null),
        assert(shadowColor != null),
        assert(clipBehavior != null),
@@ -1520,14 +1521,16 @@ abstract class _RenderPhysicalModelBase<T> extends _RenderCustomClip<T> {
        _shadowColor = shadowColor,
        super(child: child, clipBehavior: clipBehavior, clipper: clipper);
 
-  /// The z-coordinate at which to place this material.
+  /// The z-coordinate relative to the parent at which to place this material.
+  ///
+  /// The value is non-negative.
   ///
   /// If [debugDisableShadows] is set, this value is ignored and no shadow is
   /// drawn (an outline is rendered instead).
   double get elevation => _elevation;
   double _elevation;
   set elevation(double value) {
-    assert(value != null);
+    assert(value != null && value >= 0.0);
     if (elevation == value)
       return;
     final bool didNeedCompositing = alwaysNeedsCompositing;
@@ -1585,6 +1588,7 @@ class RenderPhysicalModel extends _RenderPhysicalModelBase<RRect> {
   /// The [color] is required.
   ///
   /// The [shape], [elevation], [color], and [shadowColor] must not be null.
+  /// Additionally, the [elevation] must be non-negative.
   RenderPhysicalModel({
     RenderBox child,
     BoxShape shape = BoxShape.rectangle,
@@ -1595,7 +1599,7 @@ class RenderPhysicalModel extends _RenderPhysicalModelBase<RRect> {
     Color shadowColor = const Color(0xFF000000),
   }) : assert(shape != null),
        assert(clipBehavior != null),
-       assert(elevation != null),
+       assert(elevation != null && elevation >= 0.0),
        assert(color != null),
        assert(shadowColor != null),
        _shape = shape,
@@ -1742,8 +1746,8 @@ class RenderPhysicalShape extends _RenderPhysicalModelBase<Path> {
   ///
   /// The [color] and [shape] parameters are required.
   ///
-  /// The [clipper], [elevation], [color] and [shadowColor] must
-  /// not be null.
+  /// The [clipper], [elevation], [color] and [shadowColor] must not be null.
+  /// Additionally, the [elevation] must be non-negative.
   RenderPhysicalShape({
     RenderBox child,
     @required CustomClipper<Path> clipper,
@@ -1752,7 +1756,7 @@ class RenderPhysicalShape extends _RenderPhysicalModelBase<Path> {
     @required Color color,
     Color shadowColor = const Color(0xFF000000),
   }) : assert(clipper != null),
-       assert(elevation != null),
+       assert(elevation != null && elevation >= 0.0),
        assert(color != null),
        assert(shadowColor != null),
        super(

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

@@ -748,6 +748,7 @@ class PhysicalModel extends SingleChildRenderObjectWidget {
   /// The [color] is required; physical things have a color.
   ///
   /// The [shape], [elevation], [color], and [shadowColor] must not be null.
+  /// Additionally, the [elevation] must be non-negative.
   const PhysicalModel({
     Key key,
     this.shape = BoxShape.rectangle,
@@ -758,7 +759,7 @@ class PhysicalModel extends SingleChildRenderObjectWidget {
     this.shadowColor = const Color(0xFF000000),
     Widget child,
   }) : assert(shape != null),
-       assert(elevation != null),
+       assert(elevation != null && elevation >= 0.0),
        assert(color != null),
        assert(shadowColor != null),
        super(key: key, child: child);
@@ -777,7 +778,10 @@ class PhysicalModel extends SingleChildRenderObjectWidget {
   /// This is ignored if the [shape] is not [BoxShape.rectangle].
   final BorderRadius borderRadius;
 
-  /// The z-coordinate at which to place this physical object.
+  /// The z-coordinate relative to the parent at which to place this physical
+  /// object.
+  ///
+  /// The value is non-negative.
   final double elevation;
 
   /// The background color.
@@ -836,6 +840,7 @@ class PhysicalShape extends SingleChildRenderObjectWidget {
   /// The [color] is required; physical things have a color.
   ///
   /// The [clipper], [elevation], [color], and [shadowColor] must not be null.
+  /// Additionally, the [elevation] must be non-negative.
   const PhysicalShape({
     Key key,
     @required this.clipper,
@@ -846,7 +851,7 @@ class PhysicalShape extends SingleChildRenderObjectWidget {
     Widget child,
   }) : assert(clipper != null),
        assert(clipBehavior != null),
-       assert(elevation != null),
+       assert(elevation != null && elevation >= 0.0),
        assert(color != null),
        assert(shadowColor != null),
        super(key: key, child: child);
@@ -861,7 +866,10 @@ class PhysicalShape extends SingleChildRenderObjectWidget {
   /// {@macro flutter.widgets.Clip}
   final Clip clipBehavior;
 
-  /// The z-coordinate at which to place this physical object.
+  /// The z-coordinate relative to the parent at which to place this physical
+  /// object.
+  ///
+  /// The value is non-negative.
   final double elevation;
 
   /// The background color.

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

@@ -1240,7 +1240,8 @@ class AnimatedPhysicalModel extends ImplicitlyAnimatedWidget {
   /// Creates a widget that animates the properties of a [PhysicalModel].
   ///
   /// The [child], [shape], [borderRadius], [elevation], [color], [shadowColor], [curve], and
-  /// [duration] arguments must not be null.
+  /// [duration] arguments must not be null. Additionally, [elevation] must be
+  /// non-negative.
   ///
   /// Animating [color] is optional and is controlled by the [animateColor] flag.
   ///
@@ -1262,7 +1263,7 @@ class AnimatedPhysicalModel extends ImplicitlyAnimatedWidget {
        assert(shape != null),
        assert(clipBehavior != null),
        assert(borderRadius != null),
-       assert(elevation != null),
+       assert(elevation != null && elevation >= 0.0),
        assert(color != null),
        assert(shadowColor != null),
        assert(animateColor != null),
@@ -1285,7 +1286,10 @@ class AnimatedPhysicalModel extends ImplicitlyAnimatedWidget {
   /// The target border radius of the rounded corners for a rectangle shape.
   final BorderRadius borderRadius;
 
-  /// The target z-coordinate at which to place this physical object.
+  /// The target z-coordinate relative to the parent at which to place this
+  /// physical object.
+  ///
+  /// The value will always be non-negative.
   final double elevation;
 
   /// The target background color.