Bug 1308572 - Remove references to generator special treatment from JS Debugger API docs. r=jorendorff
authorJim Blandy <jimb@red-bean.com>
Fri, 07 Oct 2016 11:28:39 -0700
changeset 343958 2c060e2559a299b74427152801308e63993e01ce
parent 343957 4c17e2d68479d6682fab60d40ca3b60e0de13f45
child 343959 2426d3b9f4d22e1a71ab43d61ad9d026bf549e3d
push id10298
push userraliiev@mozilla.com
push dateMon, 14 Nov 2016 12:33:03 +0000
treeherdermozilla-aurora@7e29173b1641 [default view] [failures only]
perfherder[talos] [build metrics] [platform microbench] (compared to previous push)
reviewersjorendorff
bugs1308572
milestone52.0a1
Bug 1308572 - Remove references to generator special treatment from JS Debugger API docs. r=jorendorff
js/src/doc/Debugger/Conventions.md
js/src/doc/Debugger/Debugger.Frame.md
js/src/doc/Debugger/Debugger.Script.md
js/src/doc/Debugger/config.sh
--- a/js/src/doc/Debugger/Conventions.md
+++ b/js/src/doc/Debugger/Conventions.md
@@ -71,20 +71,16 @@ of debuggee call initiated by the debugg
 interface provides a value describing how the code completed; these are
 called *completion values*. A completion value has one of the
 following forms:
 
 <code>{ return: <i>value</i> }</code>
 :   The code completed normally, returning <i>value</i>. <i>Value</i> is a
     debuggee value.
 
-<code>{ yield: <i>value</i> }</code>
-:   <i>(Not yet implemented.)</i> The running code is a generator frame
-    which has yielded <i>value</i>. <i>Value</i> is a debuggee value.
-
 <code>{ throw: <i>value</i> }</code>
 :   The code threw <i>value</i> as an exception. <i>Value</i> is a debuggee
     value.
 
 `null`
 :   The code was terminated, as if by the "slow script" dialog box.
 
 If control reaches the end of a generator frame, the completion value is
@@ -110,24 +106,16 @@ resumption value has one of the followin
     this, except those whose descriptions say otherwise.) If the function
     was called as a constructor (that is, via a `new` expression), then
     <i>value</i> serves as the value returned by the function's body, not
     that produced by the `new` expression: if the value is not an object,
     the `new` expression returns the frame's `this` value. Similarly, if
     the function is the constructor for a subclass, then a non-object
     value may result in a TypeError.
 
-<code>{ yield: <i>value</i> }</code>
-:   <i>(Not yet implemented.)</i> Yield <i>value</i> immediately as the
-    next value of the current frame, which must be a generator frame.
-    <i>Value</i> is a debuggee value. The current frame must be a generator
-    frame that has not yet completed in some other way. You may use `yield`
-    resumption values to substitute a new value or one already yielded by a
-    generator, or to make a generator yield additional values.
-
 <code>{ throw: <i>value</i> }</code>
 :   Throw <i>value</i> as an exception from the current bytecode
     instruction. <i>Value</i> must be a debuggee value.
 
 `null`
 :   Terminate the debuggee, as if it had been cancelled by the "slow script"
     dialog box.
 
--- a/js/src/doc/Debugger/Debugger.Frame.md
+++ b/js/src/doc/Debugger/Debugger.Frame.md
@@ -23,19 +23,16 @@ with other debuggers.)
 When the debuggee pops a stack frame (say, because a function call has
 returned or an exception has been thrown from it), the `Debugger.Frame`
 instance referring to that frame becomes inactive: its `live` property
 becomes `false`, and accessing its other properties or calling its methods
 throws an exception. Note that frames only become inactive at times that
 are predictable for the debugger: when the debuggee runs, or when the
 debugger removes frames from the stack itself.
 
-Stack frames that represent the control state of generator-iterator objects
-behave in a special way, described in [Generator Frames][generator] below.
-
 
 ## Visible Frames
 
 When inspecting the call stack, [`Debugger`][debugger-object] does not
 reveal all the frames that are actually present on the stack: while it does
 reveal all frames running debuggee code, it omits frames running the
 debugger's own code, and omits most frames running non-debuggee code. We
 call those stack frames a [`Debugger`][debugger-object] does reveal
@@ -127,28 +124,25 @@ its prototype:
 
     * `"ion"`: a frame running in the optimizing JIT.
 
 `this`
 :   The value of `this` for this frame (a debuggee value).
 
 `older`
 :   The next-older visible frame, in which control will resume when this
-    frame completes. If there is no older frame, this is `null`. (On a
-    suspended generator frame, the value of this property is `null`; see
-    [Generator Frames][generator].)
+    frame completes. If there is no older frame, this is `null`.
 
 `depth`
 :   The depth of this frame, counting from oldest to youngest; the oldest
     frame has a depth of zero.
 
 `live`
 :   True if the frame this `Debugger.Frame` instance refers to is still on
-    the stack (or, in the case of generator-iterator objects, has not yet
-    finished its iteration); false if it has completed execution or been
+    the stack; false if it has completed execution or been
     popped in some other way.
 
 `script`
 :   The script being executed in this frame (a [`Debugger.Script`][script]
     instance), or `null` on frames that do not represent calls to debuggee
     code. On frames whose `callee` property is not null, this is equal to
     `callee.script`.
 
@@ -249,42 +243,26 @@ the compartment to which the handler met
     caused the frame to complete.
 
     When SpiderMonkey calls an `onPop` handler for a frame that is throwing
     an exception or being terminated, and the handler returns `undefined`,
     then SpiderMonkey proceeds with the exception or termination. That is,
     an `undefined` resumption value leaves the frame's throwing and
     termination process undisturbed.
 
-    <i>(Not yet implemented.)</i> When a generator frame yields a value,
-    SpiderMonkey calls its `Debugger.Frame` instance's `onPop` handler
-    method, if present, passing a `yield` resumption value; however, the
-    `Debugger.Frame` instance remains live.
-
     If multiple [`Debugger`][debugger-object] instances each have
     `Debugger.Frame` instances for a given stack frame with `onPop`
     handlers set, their handlers are run in an unspecified order. The
     resumption value each handler returns establishes the completion value
     reported to the next handler.
 
     This handler is not called on `"debugger"` frames. It is also not called
     when unwinding a frame due to an over-recursion or out-of-memory
     exception.
 
-`onResume`
-:   This property must be either `undefined` or a function. If it is a
-    function, SpiderMonkey calls it if the current frame is a generator
-    frame whose execution has just been resumed. The function should return
-    a [resumption value][rv] indicating how execution should proceed. On
-    newly created frames, this property's value is `undefined`.
-
-    If the program resumed the generator by calling its `send` method and
-    passing a value, then <i>value</i> is that value. Otherwise,
-    <i>value</i> is `undefined`.
-
 
 ## Function Properties of the Debugger.Frame Prototype Object
 
 The functions described below may only be called with a `this` value
 referring to a `Debugger.Frame` instance; they may not be used as
 methods of other kinds of objects.
 
 <code id="eval">eval(<i>code</i>, [<i>options</i>])</code>
@@ -343,64 +321,8 @@ methods of other kinds of objects.
     of the execution context that this frame represents, and the
     <i>bindings</i> appear in a new declarative environment, which is the
     eval code's `LexicalEnvironment`.) If implementation restrictions
     prevent SpiderMonkey from extending this frame's environment as
     requested, this call throws an `Error` exception.
 
     The <i>options</i> argument is as for
     [`Debugger.Frame.prototype.eval`][fr eval], described above.
-
-
-## Generator Frames
-
-<i>Not all behavior described in this section has been implemented
-yet.</i>
-
-SpiderMonkey supports generator-iterator objects, which produce a series of
-values by repeatedly suspending the execution of a function or expression.
-For example, calling a function that uses `yield` produces a
-generator-iterator object, as does evaluating a generator expression like
-`(i*i for each (i in [1,2,3]))`.
-
-A generator-iterator object refers to a stack frame with no fixed
-continuation frame. While the generator's code is running, its continuation
-is whatever frame called its `next` method; while the generator is
-suspended, it has no particular continuation frame; and when it resumes
-again, the continuation frame for that resumption could be different from
-that of the previous resumption.
-
-A `Debugger.Frame` instance representing a generator frame differs from an
-ordinary stack frame as follows:
-
-* A generator frame's `generator` property is true.
-
-* A generator frame disappears from the stack each time the generator
-  yields a value and is suspended, and reappears atop the stack when it is
-  resumed to produce the generator's next value. The same `Debugger.Frame`
-  instance refers to the generator frame until it returns, throws an
-  exception, or is terminated.
-
-* A generator frame's `older` property refers to the frame's continuation
-  frame while the generator is running, and is `null` while the generator
-  is suspended.
-
-* A generator frame's `depth` property reflects the frame's position on
-  the stack when the generator is resumed, and is `null` while the
-  generator is suspended.
-
-* A generator frame's `live` property remains true until the frame
-  returns, throws an exception, or is terminated. Thus, generator frames
-  can be live while not present on the stack.
-
-The other `Debugger.Frame` methods and accessor properties work as
-described on generator frames, even when the generator frame is suspended.
-You may examine a suspended generator frame's variables, and use its
-`script` and `offset` members to see which `yield` it is suspended at.
-
-A `Debugger.Frame` instance referring to a generator-iterator frame has a
-strong reference to the generator-iterator object; the frame (and its
-object) will live as long as the `Debugger.Frame` instance does. However,
-when the generator function returns, throws an exception, or is terminated,
-thus ending the iteration, the `Debugger.Frame` instance becomes inactive
-and its `live` property becomes `false`, just as would occur for any other
-sort of frame that is popped. A non-live `Debugger.Frame` instance no
-longer holds a strong reference to the generator-iterator object.
--- a/js/src/doc/Debugger/Debugger.Script.md
+++ b/js/src/doc/Debugger/Debugger.Script.md
@@ -320,18 +320,18 @@ methods of other kinds of objects.
     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`.
 
     **If the instance refers to WebAssembly code**, throw a `TypeError`.
 
 `getChildScripts()`
 :   **If the instance refers to a `JSScript`**, 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
+    elements are Debugger.Script objects for each function
+    in this script. Only direct children are included; nested
     children can be reached by walking the tree.
 
     **If the instance refers to WebAssembly code**, throw a `TypeError`.
 
 <code>setBreakpoint(<i>offset</i>, <i>handler</i>)</code>
 :   **If the instance refers to a `JSScript`**, set a breakpoint at the
     bytecode instruction at <i>offset</i> in this script, reporting hits to
     the `hit` method of <i>handler</i>. If <i>offset</i> is not a valid offset
--- a/js/src/doc/Debugger/config.sh
+++ b/js/src/doc/Debugger/config.sh
@@ -19,17 +19,16 @@ markdown Debugger.md Debugger-API/Debugg
   label 'add'           '#addDebuggee'          "The Debugger object: addDebuggee"
 
 markdown Debugger.Environment.md Debugger-API/Debugger.Environment
   label 'environment'                           "Debugger.Environment"
 
 markdown Debugger.Frame.md Debugger-API/Debugger.Frame
   label 'frame'                                 "Debugger.Frame"
   label 'vf'            '#visible-frames'       "Debugger.Frame: Visible Frames"
-  label 'generator'     '#generator-frames'     "Debugger.Frame: Generator Frames"
   label 'inv fr'        '#invf'                 "Debugger.Frame: Invocation Frames"
   label 'fr eval'       '#eval'                 "Debugger.Frame: Eval"
 
 markdown Debugger.Object.md Debugger-API/Debugger.Object
   label 'object'                                "Debugger.Object"
   label 'allocation-site' '#allocationsite'     "Debugger.Object: allocationSite"
 
 markdown Debugger.Script.md Debugger-API/Debugger.Script