Improve elevation docs (#3502)

Fixes #3501

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

@@ -96,6 +96,8 @@ class AppBar extends StatelessWidget {
   final TabBar<dynamic> tabBar;
 
   /// The z-coordinate at which to place this app bar.
+  ///
+  /// The following elevations have defined shadows: 1, 2, 3, 4, 6, 8, 9, 12, 16, 24
   final int elevation;
 
   /// The color to use for the the app bar's material.

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

@@ -51,6 +51,8 @@ class Drawer extends StatelessWidget {
   }) : super(key: key);
 
   /// The z-coordinate at which to place this drawer.
+  ///
+  /// The following elevations have defined shadows: 1, 2, 3, 4, 6, 8, 9, 12, 16, 24
   final int elevation;
 
   /// The widget below this widget in the tree.

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

@@ -43,7 +43,7 @@ class _DropDownMenuPainter extends CustomPainter {
     final BoxPainter painter = new BoxDecoration(
       backgroundColor: color,
       borderRadius: 2.0,
-      boxShadow: elevationToShadow[elevation]
+      boxShadow: kElevationToShadow[elevation]
     ).createBoxPainter();
 
     double top = renderBox.globalToLocal(new Point(0.0, menuTop)).y;
@@ -310,6 +310,8 @@ class DropDownButton<T> extends StatefulWidget {
   final ValueChanged<T> onChanged;
 
   /// The z-coordinate at which to place the menu when open.
+  ///
+  /// The following elevations have defined shadows: 1, 2, 3, 4, 6, 8, 9, 12, 16, 24
   final int elevation;
 
   @override

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

@@ -73,6 +73,8 @@ class FloatingActionButton extends StatefulWidget {
   final VoidCallback onPressed;
 
   /// The z-coordinate at which to place this button.
+  ///
+  /// The following elevations have defined shadows: 1, 2, 3, 4, 6, 8, 9, 12, 16, 24
   final int elevation;
 
   /// The z-coordinate at which to place this button when the user is touching the button.

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

@@ -181,6 +181,8 @@ class Material extends StatefulWidget {
   final MaterialType type;
 
   /// The z-coordinate at which to place this material.
+  ///
+  /// The following elevations have defined shadows: 1, 2, 3, 4, 6, 8, 9, 12, 16, 24
   final int elevation;
 
   /// The color to paint the material.
@@ -266,7 +268,7 @@ class _MaterialState extends State<Material> {
         duration: kThemeChangeDuration,
         decoration: new BoxDecoration(
           borderRadius: kMaterialEdges[config.type],
-          boxShadow: config.elevation == 0 ? null : elevationToShadow[config.elevation],
+          boxShadow: config.elevation == 0 ? null : kElevationToShadow[config.elevation],
           shape: config.type == MaterialType.circle ? BoxShape.circle : BoxShape.rectangle
         ),
         child: new Container(

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

@@ -417,6 +417,8 @@ class PopupMenuButton<T> extends StatefulWidget {
   final String tooltip;
 
   /// The z-coordinate at which to place the menu when open.
+  ///
+  /// The following elevations have defined shadows: 1, 2, 3, 4, 6, 8, 9, 12, 16, 24
   final int elevation;
 
   /// The widget below this widget in the tree.

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

@@ -57,6 +57,8 @@ class RaisedButton extends MaterialButton {
   final Color disabledColor;
 
   /// The z-coordinate at which to place this button.
+  ///
+  /// The following elevations have defined shadows: 1, 2, 3, 4, 6, 8, 9, 12, 16, 24
   final int elevation;
 
   /// The z-coordinate at which to place this button when highlighted.

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

@@ -18,9 +18,10 @@ import 'package:flutter/painting.dart';
 /// effect for that elevation.
 ///
 /// See also:
+///
 ///  * [Material]
 ///  * <https://www.google.com/design/spec/what-is-material/elevation-shadows.html>
-const Map<int, List<BoxShadow>> elevationToShadow = _elevationToShadow; // to hide the literal from the docs
+const Map<int, List<BoxShadow>> kElevationToShadow = _elevationToShadow; // to hide the literal from the docs
 
 const Color _kKeyUmbraOpacity = const Color(0x33000000); // alpha = 0.2
 const Color _kKeyPenumbraOpacity = const Color(0x24000000); // alpha = 0.14

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

@@ -268,7 +268,7 @@ class _RenderSwitch extends RenderToggleable {
     return new BoxDecoration(
       backgroundColor: color,
       shape: BoxShape.circle,
-      boxShadow: elevationToShadow[1]
+      boxShadow: kElevationToShadow[1]
     );
   }
 

packages/flutter/test/rendering/box_test.dart

@@ -16,7 +16,7 @@ void main() {
         gradient: new RadialGradient(
           center: FractionalOffset.topLeft, radius: 1.8,
           colors: <Color>[Colors.yellow[500], Colors.blue[500]]),
-        boxShadow: elevationToShadow[3])
+        boxShadow: kElevationToShadow[3])
     );
     layout(root);
     expect(root.size.width, equals(800.0));