Re-organize the Material widget's documentation. (flutter#14303)

amirh · web-flow · commit ae1f65ebd65c · 2018-01-26T20:09:11.000-08:00
This widget evolved over time by multiple people, I'm just trying to explain
in a more direct way what the widget is currently doing.
diff --git a/packages/flutter/lib/src/material/material.dart b/packages/flutter/lib/src/material/material.dart
@@ -35,6 +35,15 @@ enum MaterialType {
   button,
 
   /// A transparent piece of material that draws ink splashes and highlights.
+  ///
+  /// While the material metaphor describes child widgets as printed on the
+  /// material itself and do not hide ink effects, in practice the [Material]
+  /// widget draws child widgets on top of the ink effects.
+  /// A [Material] with type transparency can be placed on top of opaque widgets
+  /// to show ink effects on top of them.
+  ///
+  /// Prefer using the [Ink] widget for showing ink effects on top of opaque
+  /// widgets.
   transparency
 }
 
@@ -76,6 +85,17 @@ abstract class MaterialInkController {
 
 /// A piece of material.
 ///
+/// The Material widget is responsible for:
+///
+/// 1. Clipping: Material clips its widget sub-tree to the shape specified by
+///    [type] and [borderRadius].
+/// 2. Elevation: Material elevates its widget sub-tree on the Z axis by
+///    [elevation] pixels, and draws the appropriate shadow.
+/// 3. Ink effects: Material shows ink effects implemented by [InkFeature]s
+///    like [InkSplash] and [InkHighlight] below its children.
+///
+/// ## The Material Metaphor
+///
 /// Material is the central metaphor in material design. Each piece of material
 /// exists at a given elevation, which influences how that piece of material
 /// visually relates to other pieces of material and how that material casts
@@ -86,9 +106,26 @@ abstract class MaterialInkController {
 /// [InkSplash] and [InkHighlight] effects. To trigger a reaction on the
 /// material, use a [MaterialInkController] obtained via [Material.of].
 ///
-/// If a material has a non-zero [elevation], then the material will clip its
-/// contents because content that is conceptually printing on a separate piece
-/// of material cannot be printed beyond the bounds of the material.
+/// In general, the features of a [Material] should not change over time (e.g. a
+/// [Material] should not change its [color], [shadowColor] or [type]). The one
+/// exception is the [elevation], changes to which will be animated.
+///
+/// ## Shape
+///
+/// The shape for material is determined by [type] and [borderRadius].
+///
+///  - If [borderRadius] is non null, the shape is a rounded rectangle, with
+///    corners specified by [borderRadius].
+///  - If [borderRadius] is null, [type] determines the shape as follows:
+///    - [MaterialType.canvas]: the default material shape is a rectangle.
+///    - [MaterialType.card]: the default material shape is a rectangle with
+///      rounded edges. The edge radii is specified by [kMaterialEdges].
+///    - [MaterialType.circle]: the default material shape is a circle.
+///    - [MaterialType.button]: the default material shape is a rectangle with
+///      rounded edges. The edge radii is specified by [kMaterialEdges].
+///    - [MaterialType.transparency]: the default material shape is a rectangle.
+///
+/// ## Layout change notifications
 ///
 /// If the layout changes (e.g. because there's a list on the material, and it's
 /// been scrolled), a [LayoutChangedNotification] must be dispatched at the
@@ -99,10 +136,6 @@ abstract class MaterialInkController {
 /// features (e.g., ink splashes and ink highlights) won't move to account for
 /// the new layout.
 ///
-/// In general, the features of a [Material] should not change over time (e.g. a
-/// [Material] should not change its [color], [shadowColor] or [type]). The one
-/// exception is the [elevation], changes to which will be animated.
-///
 /// See also:
 ///
 /// * [MergeableMaterial], a piece of material that can split and remerge.
