RPP: add JSDoc explaining timelineData.markers

I got confused about what we use them for the other day and how we draw
LCP/etc markers. Leaving this comment to at least help the next person
out.

[email protected]

Bug: none
Change-Id: I0bd0e5926e0e1ac5c33010bfc834d396b1649eeb
Reviewed-on: https://chromium-review.googlesource.com/c/devtools/devtools-frontend/+/6891412
Commit-Queue: Paul Irish <[email protected]>
Auto-Submit: Jack Franklin <[email protected]>
Reviewed-by: Paul Irish <[email protected]>

Author: jackfranklin

front_end/panels/timeline/TimingsTrackAppender.ts

@@ -115,8 +115,7 @@ export class TimingsTrackAppender implements TrackAppender {
    * extension markers (the first available level to append more data).
    */
   #appendExtensionsAtLevel(currentLevel: number): number {
-    let markers: Trace.Types.Extensions.SyntheticExtensionMarker[] = [];
-    markers = markers.concat(this.#extensionMarkers).sort((m1, m2) => m1.ts - m2.ts);
+    const markers = this.#extensionMarkers.toSorted((m1, m2) => m1.ts - m2.ts);
     if (markers.length === 0) {
       return currentLevel;
     }

front_end/ui/legacy/components/perf_ui/FlameChart.ts

@@ -4194,6 +4194,18 @@ export class FlameChartTimelineData {
    **/
   entryDecorations: FlameChartDecoration[][];
   groups: Group[];
+
+  /**
+   * Markers are events with vertical lines that go down the entire timeline at their start time.
+   * These are only used now in the Extensibility API; users can provide a
+   * `marker` event
+   * (https://developer.chrome.com/docs/devtools/performance/extension#inject_your_data_with_the_user_timings_api)
+   * which will render with a vertical line.
+   * If you are wondering what we use to draw page events like LCP, those are
+   * done via the overlays system. In time, it probably makes sense to use the
+   * overlays for e11y marker events too, and then we can remove markers from
+   * TimelineData, rather than have two systems to build the same UI...
+   */
   markers: FlameChartMarker[];
 
   // These four arrays are used to draw the initiator arrows, and if there are