Document GridPaper (#10357)

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

@@ -246,7 +246,7 @@ class _MaterialAppState extends State<MaterialApp> {
         checkerboardRasterCacheImages: widget.checkerboardRasterCacheImages,
         checkerboardOffscreenLayers: widget.checkerboardOffscreenLayers,
         showSemanticsDebugger: widget.showSemanticsDebugger,
-        debugShowCheckedModeBanner: widget.debugShowCheckedModeBanner
+        debugShowCheckedModeBanner: widget.debugShowCheckedModeBanner,
       )
     );
 
@@ -256,8 +256,8 @@ class _MaterialAppState extends State<MaterialApp> {
           color: const Color(0xE0F9BBE0),
           interval: 8.0,
           divisions: 2,
-          subDivisions: 1,
-          child: result
+          subdivisions: 1,
+          child: result,
         );
       }
       return true;
@@ -265,7 +265,7 @@ class _MaterialAppState extends State<MaterialApp> {
 
     return new ScrollConfiguration(
       behavior: new _MaterialScrollBehavior(),
-      child: result
+      child: result,
     );
   }
 }

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

@@ -12,25 +12,25 @@ class _GridPaperPainter extends CustomPainter {
     this.color,
     this.interval,
     this.divisions,
-    this.subDivisions
+    this.subdivisions
   });
 
   final Color color;
   final double interval;
   final int divisions;
-  final int subDivisions;
+  final int subdivisions;
 
   @override
   void paint(Canvas canvas, Size size) {
     final Paint linePaint = new Paint()
       ..color = color;
-    final double allDivisions = (divisions * subDivisions).toDouble();
+    final double allDivisions = (divisions * subdivisions).toDouble();
     for (double x = 0.0; x <= size.width; x += interval / allDivisions) {
-      linePaint.strokeWidth = (x % interval == 0.0) ? 1.0 : (x % (interval / subDivisions) == 0.0) ? 0.5: 0.25;
+      linePaint.strokeWidth = (x % interval == 0.0) ? 1.0 : (x % (interval / subdivisions) == 0.0) ? 0.5 : 0.25;
       canvas.drawLine(new Offset(x, 0.0), new Offset(x, size.height), linePaint);
     }
     for (double y = 0.0; y <= size.height; y += interval / allDivisions) {
-      linePaint.strokeWidth = (y % interval == 0.0) ? 1.0 : (y % (interval / subDivisions) == 0.0) ? 0.5: 0.25;
+      linePaint.strokeWidth = (y % interval == 0.0) ? 1.0 : (y % (interval / subdivisions) == 0.0) ? 0.5 : 0.25;
       canvas.drawLine(new Offset(0.0, y), new Offset(size.width, y), linePaint);
     }
   }
@@ -40,38 +40,65 @@ class _GridPaperPainter extends CustomPainter {
     return oldPainter.color != color
         || oldPainter.interval != interval
         || oldPainter.divisions != divisions
-        || oldPainter.subDivisions != subDivisions;
+        || oldPainter.subdivisions != subdivisions;
   }
 
   @override
   bool hitTest(Offset position) => false;
 }
 
-/// A widget that draws a rectilinear grid of 1px wide lines.
+/// A widget that draws a rectilinear grid of lines one pixel wide.
 ///
 /// Useful with a [Stack] for visualizing your layout along a grid.
+///
+/// The grid's origin (where the first primary horizontal line and the first
+/// primary vertical line intersect) is at the top left of the widget.
+///
+/// The grid is drawn over the [child] widget.
 class GridPaper extends StatelessWidget {
-  /// Creates a widget that draws a rectilinear grid of 1px wide lines.
+  /// Creates a widget that draws a rectilinear grid of 1-pixel-wide lines.
   const GridPaper({
     Key key,
     this.color: const Color(0x7FC3E8F3),
     this.interval: 100.0,
     this.divisions: 2,
-    this.subDivisions: 5,
-    this.child
-  }) : super(key: key);
+    this.subdivisions: 5,
+    this.child,
+  }) : assert(divisions > 0, 'The "divisions" property must be greater than zero. If there were no divisions, the grid paper would not paint anything.'),
+       assert(subdivisions > 0, 'The "subdivisions" property must be greater than zero. If there were no subdivisions, the grid paper would not paint anything.'),
+       super(key: key);
 
   /// The color to draw the lines in the grid.
+  ///
+  /// Defaults to a light blue commonly seen on traditional gridpaper.
   final Color color;
 
   /// The distance between the primary lines in the grid, in logical pixels.
+  ///
+  /// Each primary line is one logical pixel wide.
   final double interval;
 
   /// The number of major divisions within each primary grid cell.
+  ///
+  /// This is the number of major divisions per [interval], including the
+  /// primary grid's line.
+  ///
+  /// The lines after the first are half a logical pixel wide.
+  ///
+  /// If this is set to 2 (the default), then for each [interval] there will be
+  /// a 1-pixel line on the left, a half-pixel line in the middle, and a 1-pixel
+  /// line on the right (the latter being the 1-pixel line on the left of the
+  /// next [interval]).
   final int divisions;
 
-  /// The number of minor divisions within each major division.
-  final int subDivisions;
+  /// The number of minor divisions within each major division, including the
+  /// major division itself.
+  ///
+  /// If [subdivisions] is 5 (the default), it means that there will be four
+  /// lines between each major ([divisions]) line.
+  ///
+  /// The subdivision lines after the first are a quarter of a logical pixel wide.
+  final int subdivisions;
 
   /// The widget below this widget in the tree.
   final Widget child;
@@ -83,9 +110,9 @@ class GridPaper extends StatelessWidget {
         color: color,
         interval: interval,
         divisions: divisions,
-        subDivisions: subDivisions
+        subdivisions: subdivisions,
       ),
-      child: child
+      child: child,
     );
   }
 }