Document StatisticsOverlay.rasterizerThreshold

sky/packages/sky/lib/src/widgets/statistics_overlay.dart

@@ -51,6 +51,33 @@ class StatisticsOverlay extends LeafRenderObjectWidget {
   );
 
   final int optionsMask;
+
+  /// The rasterizer threshold is an integer specifying the number of frame
+  /// intervals that the rasterizer must miss before it decides that the frame
+  /// is suitable for capturing an SkPicture trace from for further analysis.
+  ///
+  /// For example, if you want a trace of all pictures that could not be
+  /// renderered by the rasterizer within the frame boundary (and hence caused
+  /// jank), specify 1. Specifying 2 will trace all pictures that took more
+  /// more than 2 frame intervals to render. Adjust this value to only capture
+  /// the particularly expensive pictures while skipping the others. Specifying
+  /// 0 disables all capture.
+  ///
+  /// Captured traces are placed on your device in the application documents
+  /// directory in this form "trace_<timestamp_since_app_start>.skp". These can
+  /// be viewed in the Skia debugger.
+  ///
+  /// Notes:
+  /// The rasterizer only takes into account the time it took to render
+  /// the already constructed picture. This include the Skia calls (which is
+  /// also why an SkPicture trace is generated) but not any of the time spent in
+  /// dart to construct that picture. To profile that part of your code, use
+  /// the instrumentation available in observatory.
+  ///
+  /// To decide what threshold interval to use, count the number of horizontal
+  /// lines displayed in the statistics overlay for the rasterizer (not the
+  /// engine). That should give an idea of how often frames are skipped (and by
+  /// how many frame intervals).
   final int rasterizerThreshold;
 
   StatisticsBox createRenderObject() => new StatisticsBox(