Bug 1176880 part 3 - Debugger.Script.getOffsetsCoverage: Add documentation. r=shu
authorNicolas B. Pierron <nicolas.b.pierron@mozilla.com>
Wed, 16 Sep 2015 21:11:35 +0200
changeset 297179 26ca3396791f227f6402bb51a58ff727784ca939
parent 297178 b617f0a6a77c649d1f4c721b0548501a6f54c2a0
child 297180 cdbdb471f9c790e5f8f3e0a4cc372ff5266af2e3
push id962
push userjlund@mozilla.com
push dateFri, 04 Dec 2015 23:28:54 +0000
treeherdermozilla-release@23a2d286e80f [default view] [failures only]
perfherder[talos] [build metrics] [platform microbench] (compared to previous push)
reviewersshu
bugs1176880
milestone43.0a1
first release with
nightly linux32
nightly linux64
nightly mac
nightly win32
nightly win64
last release without
nightly linux32
nightly linux64
nightly mac
nightly win32
nightly win64
Bug 1176880 part 3 - Debugger.Script.getOffsetsCoverage: Add documentation. r=shu
js/src/doc/Debugger/Debugger.Script.md
js/src/doc/Debugger/Debugger.md
--- a/js/src/doc/Debugger/Debugger.Script.md
+++ b/js/src/doc/Debugger/Debugger.Script.md
@@ -197,26 +197,44 @@ methods of other kinds of objects.
 
     Calling `getAllColumnOffsets()` on that code might yield an array like this:
 
     ```language-js
     [{ lineNumber: 0, columnNumber: 0, offset: 0 },
      { lineNumber: 1, columnNumber: 5, offset: 5 },
      { lineNumber: 1, columnNumber: 10, offset: 20 },
      { lineNumber: 3, columnNumber: 4, offset: 10 }]
+    ```
 
 <code>getLineOffsets(<i>line</i>)</code>
 :   Return an array of bytecode instruction offsets representing the entry
     points to source line <i>line</i>. If the script contains no executable
     code at that line, the array returned is empty.
 
 <code>getOffsetLine(<i>offset</i>)</code>
 :   Return the source code line responsible for the bytecode at
     <i>offset</i> in this script.
 
+`getOffsetsCoverage()`:
+:   Return `null` or an array which contains informations about the coverage of
+    all opcodes. The elements of the array are objects, each of which describes
+    a single opcode, and contains the following properties:
+
+    * lineNumber: the line number of the current opcode.
+
+    * columnNumber: the column number of the current opcode.
+
+    * offset: the bytecode instruction offset of the current opcode.
+
+    * count: the number of times the current opcode got executed.
+
+    If this script has no coverage, or if it is not instrumented, then this
+    function will return `null`. To ensure that the debuggee is instrumented,
+    the flag `Debugger.collectCoverageInfo` should be set to `true`.
+
 `getChildScripts()`
 :   Return a new array whose elements are Debugger.Script objects for each
     function and each generator expression in this script. Only direct
     children are included; nested children can be reached by walking the
     tree.
 
 <code>setBreakpoint(<i>offset</i>, <i>handler</i>)</code>
 :   Set a breakpoint at the bytecode instruction at <i>offset</i> in this
--- a/js/src/doc/Debugger/Debugger.md
+++ b/js/src/doc/Debugger/Debugger.md
@@ -32,16 +32,34 @@ its prototype:
     ahead-of-time asm.js compiler and forces asm.js code to run as normal
     JavaScript. This is an accessor property with a getter and setter. It is
     initially `false` in a freshly created `Debugger` instance.
 
     Setting this flag to `true` is intended for uses of subsystems of the
     Debugger API (e.g, [`Debugger.Source`][source]) for purposes other than
     step debugging a target JavaScript program.
 
+`collectCoverageInfo`
+:   A boolean value indicating whether code coverage should be enabled inside
+    each debuggee of this `Debugger` instance. Changing this flag value will
+    recompile all JIT code to add or remove code coverage
+    instrumentation. Changing this flag when any frame of the debuggee is
+    currently active on the stack will produce an exception.
+
+    Setting this to `true` enables code coverage instrumentation, which can be
+    accessed via the [`Debugger.Script`][script] `getOffsetsCoverage`
+    function. In some cases, the code coverage might expose information which
+    pre-date the modification of this flag. Code coverage reports are monotone,
+    thus one can take a snapshot when the Debugger is enabled, and output the
+    difference.
+
+    Setting this to `false` prevents this `Debugger` instance from requiring any
+    code coverage instrumentation, but it does not guarantee that the
+    instrumentation is not present.
+
 `uncaughtExceptionHook`
 :   Either `null` or a function that SpiderMonkey calls when a call to a
     debug event handler, breakpoint handler, watchpoint handler, or similar
     function throws some exception, which we refer to as
     <i>debugger-exception</i> here. Exceptions thrown in the debugger are
     not propagated to debuggee code; instead, SpiderMonkey calls this
     function, passing <i>debugger-exception</i> as its sole argument and
     the `Debugger` instance as the `this` value. This function should