PR comments.

Author: kinyoklion

packages/telemetry/browser-telemetry/src/stack/StackParser.ts

@@ -4,6 +4,16 @@ import { StackFrame } from '../api/stack/StackFrame';
 import { StackTrace } from '../api/stack/StackTrace';
 import { ParsedStackOptions } from '../options';
 
+/**
+ * In the browser we will not always be able to determine the source file that code originates
+ * from. When you access a route it may just return HTML with embedded source, or just source,
+ * in which case there may not be a file name.
+ *
+ * There will also be cases where there is no source file, such as when running with various
+ * dev servers.
+ *
+ * In these situations we use this constant in place of the file name.
+ */
 const INDEX_SPECIFIER = '(index)';
 
 /**
@@ -18,12 +28,19 @@ export function processUrlToFileName(input: string, origin: string): string {
   let cleaned = input;
   if (input.startsWith(origin)) {
     cleaned = input.slice(origin.length);
+    // If the input is a single `/` then it would get removed and we would
+    // be left with an empty string. That empty string would get replaced with
+    // the INDEX_SPECIFIER. In cases where a `/` remains, either singular
+    // or at the end of a path, then we will append the index specifier.
+    // For instance the route `/test/` would ultimately be `test/(index)`.
     if (cleaned.startsWith('/')) {
       cleaned = cleaned.slice(1);
     }
+
     if (cleaned === '') {
-      cleaned = INDEX_SPECIFIER;
+      return INDEX_SPECIFIER;
     }
+
     if (cleaned.endsWith('/')) {
       cleaned += INDEX_SPECIFIER;
     }
@@ -62,7 +79,27 @@ export function trimSourceLine(options: TrimOptions, line: string, column: numbe
 }
 
 /**
+ * Given a context get trimmed source lines within the specified range.
+ *
+ * The context is a list of source code lines, this function returns a subset of
+ * lines which have been trimmed.
+ *
+ * If an error is on a specific line of source code we want to be able to get
+ * lines before and after that line. This is done relative to the originating
+ * line of source.
+ *
+ * If you wanted to get 3 lines before the origin line, then this function would
+ * need to be called with `start: originLine - 3, end: originLine`.
+ *
+ * If the `start` would underflow the context, then the start is set to 0.
+ * If the `end` would overflow the context, then the end is set to the context
+ * length.
+ *
  * Exported for testing.
+ *
+ * @param start The inclusive start index.
+ * @param end The exclusive end index.
+ * @param trimmer Method which will trim individual lines.
  */
 export function getLines(
   start: number,
@@ -79,6 +116,13 @@ export function getLines(
 }
 
 /**
+ * Given a stack frame produce source context about that stack frame.
+ *
+ * The source context includes the source line of the stack frame, some number
+ * of lines before the line of the stack frame, and some number of lines
+ * after the stack frame. The amount of context can be controlled by the
+ * provided options.
+ *
  * Exported for testing.
  */
 export function getSrcLines(