From 64c0db4ea91bb103e9ec98ad4fc9645207e9f12c Mon Sep 17 00:00:00 2001
From: "Nicolas B. Pierron" <nicolas.b.pierron@mozilla.com>
Date: Wed, 16 Sep 2015 21:11:35 +0200
Subject: [PATCH] Bug 1176880 part 3 - Debugger.Script.getOffsetsCoverage: Add
 documentation. r=shu

---
 js/src/doc/Debugger/Debugger.Script.md | 18 ++++++++++++++++++
 js/src/doc/Debugger/Debugger.md        | 18 ++++++++++++++++++
 2 files changed, 36 insertions(+)

diff --git a/js/src/doc/Debugger/Debugger.Script.md b/js/src/doc/Debugger/Debugger.Script.md
index c922d4b581e0..2ed96d39e241 100644
--- a/js/src/doc/Debugger/Debugger.Script.md
+++ b/js/src/doc/Debugger/Debugger.Script.md
@@ -202,6 +202,7 @@ methods of other kinds of objects.
      { 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
@@ -212,6 +213,23 @@ methods of other kinds of objects.
 :   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
diff --git a/js/src/doc/Debugger/Debugger.md b/js/src/doc/Debugger/Debugger.md
index df6ca9a7b0fb..8048fcd8fd7f 100644
--- a/js/src/doc/Debugger/Debugger.md
+++ b/js/src/doc/Debugger/Debugger.md
@@ -37,6 +37,24 @@ its prototype:
     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