Add comments to flutter_driver for timeline class (#58823)

* Add comments to flutter_driver for timeline class

Mostly about explanation for the json items from
timeline.dart and timeline_summary.dart.

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

@@ -20,6 +20,9 @@ class Timeline {
   final Map<String, dynamic> json;
 
   /// List of all timeline events.
+  ///
+  /// This is parsed from "traceEvents" data within [json] and sorted by
+  /// timestamp. Anything without a valid timestamp is put in the beginning.
   final List<TimelineEvent> events;
 }
 

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

@@ -62,7 +62,7 @@ class TimelineSummary {
     .where((Duration duration) => duration > kBuildBudget)
     .length;
 
-  /// Average amount of time spent per frame in the GPU rasterizer.
+  /// Average amount of time spent per frame in the engine rasterizer.
   ///
   /// Returns null if no frames were recorded.
   double computeAverageFrameRasterizerTimeMillis() {
@@ -96,6 +96,61 @@ class TimelineSummary {
   int countRasterizations() => _extractGpuRasterizerDrawDurations().length;
 
   /// Encodes this summary as JSON.
+  ///
+  /// Data ends with "_time_millis" means time in milliseconds and numbers in
+  /// the "frame_build_times", "frame_rasterizer_times", "frame_begin_times" and
+  /// "frame_rasterizer_begin_times" lists are in microseconds.
+  ///
+  /// * "average_frame_build_time_millis": Average amount of time spent per
+  ///   frame in the framework building widgets, updating layout, painting and
+  ///   compositing.
+  ///   See [computeAverageFrameBuildTimeMillis].
+  /// * "90th_percentile_frame_build_time_millis" and
+  ///   "99th_percentile_frame_build_time_millis": The p-th percentile frame
+  ///   rasterization time in milliseconds. 90 and 99-th percentile number is
+  ///   usually a better metric to estimate worse cases. See discussion in
+  ///   https://github.com/flutter/flutter/pull/19121#issuecomment-419520765
+  ///   See [computePercentileFrameBuildTimeMillis].
+  /// * "worst_frame_build_time_millis": The longest frame build time.
+  ///   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].
+  /// * "average_frame_rasterizer_time_millis": Average amount of time spent
+  ///   per frame in the engine rasterizer.
+  ///   See [computeAverageFrameRasterizerTimeMillis].
+  /// * "90th_percentile_frame_rasterizer_time_millis" and
+  ///   "99th_percentile_frame_rasterizer_time_millis": The 90/99-th percentile
+  ///   frame rasterization time in milliseconds.
+  ///   See [computePercentileFrameRasterizerTimeMillis].
+  /// * "worst_frame_rasterizer_time_millis": The longest frame rasterization
+  ///   time.
+  ///   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].
+  /// * "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.
+  ///   See [countFrames].
+  /// * "frame_rasterizer_count": The total number of rasterizer cycles recorded
+  ///   in the timeline. This is also the length of the "frame_rasterizer_times"
+  ///   and the "frame_rasterizer_begin_times" lists.
+  ///   See [countRasterizations].
+  /// * "frame_build_times": The build time of each frame, by tracking the
+  ///   [TimelineEvent] with name [kBuildFrameEventName].
+  /// * "frame_rasterizer_times": The rasterize time of each frame, by tracking
+  ///   the [TimelineEvent] with name [kRasterizeFrameEventName]
+  /// * "frame_begin_times": The build begin timestamp of each frame.
+  /// * "frame_rasterizer_begin_times": The rasterize begin time of each frame.
+  /// * "average_vsync_transitions_missed": Computes the average of the
+  ///   `vsync_transitions_missed` over the lag events.
+  ///   See [sceneDisplayLagSummarizer.computeAverageVsyncTransitionsMissed].
+  /// * "90th_percentile_vsync_transitions_missed" and
+  ///   "99th_percentile_vsync_transitions_missed": The 90/99-th percentile
+  ///   `vsync_transitions_missed` over the lag events.
+  ///   See [sceneDisplayLagSummarizer.computePercentileVsyncTransitionsMissed].
   Map<String, dynamic> get summaryJson {
     final SceneDisplayLagSummarizer sceneDisplayLagSummarizer = _sceneDisplayLagSummarizer();
     final Map<String, dynamic> profilingSummary = _profilingSummarizer().summarize();
@@ -135,6 +190,10 @@ class TimelineSummary {
   }
 
   /// Writes all of the recorded timeline data to a file.
+  ///
+  /// See also:
+  ///
+  /// * [Timeline.fromJson], which explains detail about the timeline data.
   Future<void> writeTimelineToFile(
     String traceName, {
     String destinationDirectory,
@@ -202,6 +261,12 @@ class TimelineSummary {
 
   /// Extracts Duration list that are reported as a pair of begin/end events.
   ///
+  /// Extracts Duration of events by looking for events with the name and phase
+  /// begin ("ph": "B"). This routine assumes that the next event with the same
+  /// name is phase end ("ph": "E"), but it's not examined.
+  /// "SceneDisplayLag" event is an exception, with phase ("ph") labeled
+  /// 'b' and 'e', meaning begin and end phase for an async event.
+  /// See [SceneDisplayLagSummarizer].
   /// See: https://docs.google.com/document/d/1CvAClvFfyA5R-PhYUmn5OOQtYMH4h6I0nSsKchNAySU
   List<Duration> _extractBeginEndEvents(String name) {
     return _extractDurations(