fixup! Document source maps

Author: vouillon

compiler/lib/js_output.ml

@@ -43,6 +43,8 @@
 (*
 Source maps
 ===========
+Most of this information was obtained by running the Firefox and
+Chrome debuggers on some test programs.
 
 The location of a declaration is determined by the first character of
 the expression.
@@ -74,8 +76,8 @@ Chrome stops on the character right after.
     (x)=>x+1
            ^^
 
-In Chrome the location of a function call is determined by the name of the
-function when it is explicit.
+In Chrome the location of a function call is at the start of the name
+of the function when it is explicit.
 
     f(e)         Math.cos(1.)
     ^                 ^
@@ -86,29 +88,35 @@ always uses this location.
     (0,f)(e)(e')
          ^  ^
 
-Except for variable declarations, Chrome stops at the begining of
-statements.
+Usually, Chrome stops at the begining of statements.
 
    if (e) { ... }
    ^
 
-Firefox will rather stop on the expression.
-
+Firefox will rather stop on the expression when there is one.
 
    if (e) { ... }
        ^
 
+The debugger don't stop at some statements, such as function
+declarations, labelled statements, and block statements.
+
 Chrome uses the name associated to the location of each bound variable
-to determine its name.
+to determine its name [1].
 
    function f(x) { var y = ... }
             ^ ^        ^
 
 Chrome uses the location of the opening parenthesis of a function
-declaration to determine the function name in the stack.
+declaration to determine the function name in the stack [2].
+
 
     function f() { ... }
               ^
+
+[1] https://github.com/ChromeDevTools/devtools-frontend/blob/11db398f811784395a6706cf3f800014d98171d9/front_end/models/source_map_scopes/NamesResolver.ts#L238-L243
+
+[2] https://github.com/ChromeDevTools/devtools-frontend/blob/11db398f811784395a6706cf3f800014d98171d9/front_end/models/source_map_scopes/NamesResolver.ts#L765-L768
 *)
 
 open! Stdlib