Document that missed_frame_build_budget_count is misleading (#132137)

Fixes flutter/flutter#109745

Author: Hixie

packages/flutter_driver/lib/src/driver/timeline_summary.dart

@@ -31,7 +31,11 @@ generated by the interaction.
 ''';
 
 /// The maximum amount of time considered safe to spend for a frame's build
-/// phase. Anything past that is in the danger of missing the frame as 60FPS.
+/// phase. Anything past that is in the danger of missing the frame at 60FPS.
+///
+/// This is a hard-coded number and does not take into account the real device
+/// frame rate. Prefer using percentiles on the total build or raster time
+/// than metrics based on this value.
 const Duration kBuildBudget = Duration(milliseconds: 16);
 
 /// The name of the framework frame build events we need to filter or extract.
@@ -71,9 +75,14 @@ class TimelineSummary {
 
   /// The number of frames that missed the [kBuildBudget] and therefore are
   /// in the danger of missing frames.
-  int computeMissedFrameBuildBudgetCount([ Duration frameBuildBudget = kBuildBudget ]) => _extractFrameDurations()
-    .where((Duration duration) => duration > kBuildBudget)
-    .length;
+  ///
+  /// This does not take into account the real device frame rate. Prefer using
+  /// [computePercentileFrameBuildTimeMillis] for evaluating performance.
+  int computeMissedFrameBuildBudgetCount() {
+    return _extractFrameDurations()
+        .where((Duration duration) => duration > kBuildBudget)
+        .length;
+  }
 
   /// Average amount of time spent per frame in the engine rasterizer.
   ///
@@ -112,9 +121,14 @@ class TimelineSummary {
 
   /// The number of frames that missed the [kBuildBudget] on the raster thread
   /// and therefore are in the danger of missing frames.
-  int computeMissedFrameRasterizerBudgetCount([ Duration frameBuildBudget = kBuildBudget ]) => _extractGpuRasterizerDrawDurations()
-      .where((Duration duration) => duration > kBuildBudget)
-      .length;
+  ///
+  /// This does not take into account the real device frame rate. Prefer using
+  /// [computePercentileFrameRasterizerTimeMillis] for evaluating performance.
+  int computeMissedFrameRasterizerBudgetCount() {
+    return _extractGpuRasterizerDrawDurations()
+        .where((Duration duration) => duration > kBuildBudget)
+        .length;
+  }
 
   /// The total number of frames recorded in the timeline.
   int countFrames() => _extractFrameDurations().length;
@@ -156,7 +170,8 @@ class TimelineSummary {
   ///   See [computeWorstFrameBuildTimeMillis].
   /// * "missed_frame_build_budget_count': The number of frames that missed
   ///   the [kBuildBudget] and therefore are in the danger of missing frames.
-  ///   See [computeMissedFrameBuildBudgetCount].
+  ///   See [computeMissedFrameBuildBudgetCount]. Because [kBuildBudget] is a
+  ///   constant, this does not represent a real missed frame count.
   /// * "average_frame_rasterizer_time_millis": Average amount of time spent
   ///   per frame in the engine rasterizer.
   ///   See [computeAverageFrameRasterizerTimeMillis].
@@ -172,8 +187,9 @@ class TimelineSummary {
   ///   See [computeWorstFrameRasterizerTimeMillis].
   /// * "missed_frame_rasterizer_budget_count": The number of frames that missed
   ///   the [kBuildBudget] on the raster thread and therefore are in the danger
-  ///   of missing frames.
-  ///   See [computeMissedFrameRasterizerBudgetCount].
+  ///   of missing frames. See [computeMissedFrameRasterizerBudgetCount].
+  ///   Because [kBuildBudget] is a constant, this does not represent a real
+  ///   missed frame count.
   /// * "frame_count": The total number of frames recorded in the timeline. This
   ///   is also the length of the "frame_build_times" and the "frame_begin_times"
   ///   lists.