[RPP] Add some comments to stack trace utils in the RPP codebase

To prevent confusion about when to use which.

Bug: 374732385
Change-Id: I71dded6bfbd7a1689d70f1f704d301b18e889d71
Reviewed-on: https://chromium-review.googlesource.com/c/devtools/devtools-frontend/+/6091589
Auto-Submit: Andres Olivares <[email protected]>
Reviewed-by: Nancy Li <[email protected]>
Commit-Queue: Andres Olivares <[email protected]>

Author: and-oli

front_end/models/trace/extras/StackTraceForEvent.ts

@@ -14,6 +14,12 @@ export const stackTraceForEventInTrace =
 export function clearCacheForTrace(parsedTrace: Handlers.Types.ParsedTrace): void {
   stackTraceForEventInTrace.delete(parsedTrace);
 }
+/**
+ * This util builds a stack trace that includes async calls for a given
+ * event. It leverages data we collect from sampling to deduce sync
+ * stacks and trace event instrumentation on the V8 debugger to stitch
+ * them together.
+ */
 export function get(event: Types.Events.Event, parsedTrace: Handlers.Types.ParsedTrace): Protocol.Runtime.StackTrace|
     null {
   let cacheForTrace = stackTraceForEventInTrace.get(parsedTrace);

front_end/models/trace/helpers/Trace.ts

@@ -18,13 +18,18 @@ type MatchingPairableAsyncEvents = {
 };
 
 /**
- * Extracts the raw stack trace of known trace events. Most likely than
+ * Extracts the raw stack trace in known trace events. Most likely than
  * not you want to use `getZeroIndexedStackTraceForEvent`, which returns
  * the stack with zero based numbering. Since some trace events are
  * one based this function can yield unexpected results when used
  * indiscriminately.
+ *
+ * Note: this only returns the stack trace contained in the payload of
+ * an event, which only contains the synchronous portion of the call
+ * stack. If you want to obtain the whole stack trace you might need to
+ * use the @see Trace.Extras.StackTraceForEvent util.
  */
-export function stackTraceForEvent(event: Types.Events.Event): Types.Events.CallFrame[]|null {
+export function stackTraceInEvent(event: Types.Events.Event): Types.Events.CallFrame[]|null {
   if (event.args?.data?.stackTrace) {
     return event.args.data.stackTrace;
   }
@@ -35,10 +40,10 @@ export function stackTraceForEvent(event: Types.Events.Event): Types.Events.Call
     return event.args.beginData?.stackTrace || null;
   }
   if (Types.Extensions.isSyntheticExtensionEntry(event)) {
-    return stackTraceForEvent(event.rawSourceEvent);
+    return stackTraceInEvent(event.rawSourceEvent);
   }
   if (Types.Events.isSyntheticUserTiming(event)) {
-    return stackTraceForEvent(event.rawSourceEvent);
+    return stackTraceInEvent(event.rawSourceEvent);
   }
   if (Types.Events.isFunctionCall(event)) {
     const data = event.args.data;
@@ -398,9 +403,14 @@ export function getZeroIndexedLineAndColumnForEvent(event: Types.Events.Event):
  * that are 1 or 0 indexed.
  * This function knows which events return 1 indexed numbers and normalizes
  * them. The UI expects 0 indexed line numbers, so that is what we return.
+ *
+ * Note: this only returns the stack trace contained in the payload of
+ * an event, which only contains the synchronous portion of the call
+ * stack. If you want to obtain the whole stack trace you might need to
+ * use the @see Trace.Extras.StackTraceForEvent util.
  */
 export function getZeroIndexedStackTraceForEvent(event: Types.Events.Event): Types.Events.CallFrame[]|null {
-  const stack = stackTraceForEvent(event);
+  const stack = stackTraceInEvent(event);
   if (!stack) {
     return null;
   }

front_end/panels/timeline/components/NetworkRequestDetails.ts

@@ -229,7 +229,7 @@ export class NetworkRequestDetails extends HTMLElement {
       return null;
     }
 
-    const hasStackTrace = Trace.Helpers.Trace.stackTraceForEvent(this.#networkRequest) !== null;
+    const hasStackTrace = Trace.Helpers.Trace.stackTraceInEvent(this.#networkRequest) !== null;
 
     // If we have a stack trace, that is the most reliable way to get the initiator data and display a link to the source.
     if (hasStackTrace) {