diff -r 000000000000 -r 6474c204b198 js/src/doc/Debugger/Debugger.Object.md
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/js/src/doc/Debugger/Debugger.Object.md	Wed Dec 31 06:09:35 2014 +0100
@@ -0,0 +1,534 @@
+# Debugger.Object
+
+A `Debugger.Object` instance represents an object in the debuggee,
+providing reflection-oriented methods to inspect and modify its referent.
+The referent's properties do not appear directly as properties of the
+`Debugger.Object` instance; the debugger can access them only through
+methods like `Debugger.Object.prototype.getOwnPropertyDescriptor` and
+`Debugger.Object.prototype.defineProperty`, ensuring that the debugger will
+not inadvertently invoke the referent's getters and setters.
+
+SpiderMonkey creates exactly one `Debugger.Object` instance for each
+debuggee object it presents to a given [`Debugger`][debugger-object]
+instance: if the debugger encounters the same object through two different
+routes (perhaps two functions are called on the same object), SpiderMonkey
+presents the same `Debugger.Object` instance to the debugger each time.
+This means that the debugger can use the `==` operator to recognize when
+two `Debugger.Object` instances refer to the same debuggee object, and
+place its own properties on a `Debugger.Object` instance to store metadata
+about particular debuggee objects.
+
+JavaScript code in different compartments can have different views of the
+same object. For example, in Firefox, code in privileged compartments sees
+content DOM element objects without redefinitions or extensions made to
+that object's properties by content code. (In Firefox terminology,
+privileged code sees the element through an "xray wrapper".) To ensure that
+debugger code sees each object just as the debuggee would, each
+`Debugger.Object` instance presents its referent as it would be seen from a
+particular compartment. This "viewing compartment" is chosen to match the
+way the debugger came across the referent. As a consequence, a single
+[`Debugger`][debugger-object] instance may actually have several
+`Debugger.Object` instances: one for each compartment from which the
+referent is viewed.
+
+If more than one [`Debugger`][debugger-object] instance is debugging the
+same code, each [`Debugger`][debugger-object] gets a separate
+`Debugger.Object` instance for a given object. This allows the code using
+each [`Debugger`][debugger-object] instance to place whatever properties it
+likes on its own `Debugger.Object` instances, without worrying about
+interfering with other debuggers.
+
+While most `Debugger.Object` instances are created by SpiderMonkey in the
+process of exposing debuggee's behavior and state to the debugger, the
+debugger can use `Debugger.Object.prototype.makeDebuggeeValue` to create
+`Debugger.Object` instances for given debuggee objects, or use
+`Debugger.Object.prototype.copy` and `Debugger.Object.prototype.create` to
+create new objects in debuggee compartments, allocated as if by particular
+debuggee globals.
+
+`Debugger.Object` instances protect their referents from the garbage
+collector; as long as the `Debugger.Object` instance is live, the referent
+remains live. This means that garbage collection has no visible effect on
+`Debugger.Object` instances.
+
+
+## Accessor Properties of the Debugger.Object prototype
+
+A `Debugger.Object` instance inherits the following accessor properties
+from its prototype:
+
+`proto`
+:   The referent's prototype (as a new `Debugger.Object` instance), or
+    `null` if it has no prototype.
+
+`class`
+:   A string naming the ECMAScript `[[Class]]` of the referent.
+
+`callable`
+:   `true` if the referent is a callable object (such as a function or a
+    function proxy); false otherwise.
+
+`name`
+:   The name of the referent, if it is a named function. If the referent is
+    an anonymous function, or not a function at all, this is `undefined`.
+
+    This accessor returns whatever name appeared after the `function`
+    keyword in the source code, regardless of whether the function is the
+    result of instantiating a function declaration (which binds the
+    function to its name in the enclosing scope) or evaluating a function
+    expression (which binds the function to its name only within the
+    function's body).
+
+`displayName`
+:   The referent's display name, if the referent is a function with a
+    display name. If the referent is not a function, or if it has no display
+    name, this is `undefined`.
+
+    If a function has a given name, its display name is the same as its
+    given name. In this case, the `displayName` and `name` properties are
+    equal.
+
+    If a function has no name, SpiderMonkey attempts to infer an appropriate
+    name for it given its context. For example:
+
+        function f() {}          // display name: f (the given name)
+        var g = function () {};  // display name: g
+        o.p = function () {};    // display name: o.p
+        var q = {
+          r: function () {}      // display name: q.r
+        };
+
+    Note that the display name may not be a proper JavaScript identifier,
+    or even a proper expression: we attempt to find helpful names even when
+    the function is not immediately assigned as the value of some variable
+    or property. Thus, we use <code><i>a</i>/<i>b</i></code> to refer to
+    the <i>b</i> defined within <i>a</i>, and <code><i>a</i>&lt;</code> to
+    refer to a function that occurs somewhere within an expression that is
+    assigned to <i>a</i>. For example:
+
+        function h() {
+          var i = function() {};    // display name: h/i
+          f(function () {});        // display name: h/<
+        }
+        var s = f(function () {});  // display name: s<
+
+`parameterNames`
+:   If the referent is a debuggee function, the names of the its parameters,
+    as an array of strings. If the referent is not a debuggee function, or
+    not a function at all, this is `undefined`.
+
+    If the referent is a host function for which parameter names are not
+    available, return an array with one element per parameter, each of which
+    is `undefined`.
+
+    If the referent is a function proxy, return an empty array.
+
+    If the referent uses destructuring parameters, then the array's elements
+    reflect the structure of the parameters. For example, if the referent is
+    a function declared in this way:
+
+        function f(a, [b, c], {d, e:f}) { ... }
+
+    then this `Debugger.Object` instance's `parameterNames` property would
+    have the value:
+
+        ["a", ["b", "c"], {d:"d", e:"f"}]
+
+`script`
+:   If the referent is a function that is debuggee code, this is that
+    function's script, as a [`Debugger.Script`][script] instance. If the
+    referent is a function proxy or not debuggee code, this is `undefined`.
+
+`environment`
+:   If the referent is a function that is debuggee code, a
+    [`Debugger.Environment`][environment] instance representing the lexical
+    environment enclosing the function when it was created. If the referent
+    is a function proxy or not debuggee code, this is `undefined`.
+
+`proxyHandler`
+:   If the referent is a proxy whose handler object was allocated by
+    debuggee code, this is its handler object—the object whose methods are
+    invoked to implement accesses of the proxy's properties. If the referent
+    is not a proxy whose handler object was allocated by debuggee code, this
+    is `null`.
+
+`proxyCallTrap`
+:   If the referent is a function proxy whose handler object was allocated
+    by debuggee code, this is its call trap function—the function called
+    when the function proxy is called. If the referent is not a function
+    proxy whose handler object was allocated by debuggee code, this is
+    `null`.
+
+`proxyConstructTrap`
+:   If the referent is a function proxy whose handler object was allocated
+    by debuggee code, its construction trap function—the function called
+    when the function proxy is called via a `new` expression. If the
+    referent is not a function proxy whose handler object was allocated by
+    debuggee code, this is `null`.
+
+`global`
+:   A `Debugger.Object` instance referring to the global object in whose
+    scope the referent was allocated. This does not unwrap cross-compartment
+    wrappers: if the referent is a wrapper, the result refers to the
+    wrapper's global, not the wrapped object's global. The result refers to
+    the global directly, not via a wrapper.
+
+`hostAnnotations`
+:   A JavaScript object providing further metadata about the referent, or
+    `null` if none is available. The metadata object is in the same
+    compartment as this `Debugger.Object` instance. The same metadata
+    object is returned each time for a given `Debugger.Object` instance.
+
+    A typical JavaScript embedding provides "host objects" to expose
+    application-specific functionality to scripts. The `hostAnnotations`
+    accessor consults the embedding for additional information about the
+    referent that might be of interest to the debugger. The returned
+    object's properties' meanings are up to the embedding. For example, a
+    web browser might provide host annotations for global objects to
+    distinguish top-level windows, iframes, and internal JavaScript scopes.
+
+    By convention, host annotation objects have a string-valued `"type"`
+    property that, taken together with the object's class, indicate what
+    sort of thing the referent is. The host annotation object's other
+    properties provide further details, as appropriate for the type. For
+    example, in Firefox, a metadata object for a JavaScript Module's global
+    object might look like this:
+
+        { "type":"jsm", "uri":"resource:://gre/modules/XPCOMUtils.jsm" }
+
+    Firefox provides [DebuggerHostAnnotationsForFirefox annotations] for its
+    host objects.
+
+
+
+## Function Properties of the Debugger.Object prototype
+
+The functions described below may only be called with a `this` value
+referring to a `Debugger.Object` instance; they may not be used as methods
+of other kinds of objects. The descriptions use "referent" to mean "the
+referent of this `Debugger.Object` instance".
+
+Unless otherwise specified, these methods are not
+[invocation functions][inv fr]; if a call would cause debuggee code to run
+(say, because it gets or sets an accessor property whose handler is
+debuggee code, or because the referent is a proxy whose traps are debuggee
+code), the call throws a [`Debugger.DebuggeeWouldRun`][wouldrun] exception.
+
+<code>getProperty(<i>name</i>)</code>
+:   Return the value of the referent's property named <i>name</i>, or
+    `undefined` if it has no such property. <i>Name</i> must be a string.
+    The result is a debuggee value.
+
+<code>setProperty(<i>name</i>, <i>value</i>)</code>
+:   Store <i>value</i> as the value of the referent's property named
+    <i>name</i>, creating the property if it does not exist. <i>Name</i>
+    must be a string; <i>value</i> must be a debuggee value.
+
+<code>getOwnPropertyDescriptor(<i>name</i>)</code>
+:   Return a property descriptor for the property named <i>name</i> of the
+    referent. If the referent has no such property, return `undefined`.
+    (This function behaves like the standard
+    `Object.getOwnPropertyDescriptor` function, except that the object being
+    inspected is implicit; the property descriptor returned is allocated as
+    if by code scoped to the debugger's global object (and is thus in the
+    debugger's compartment); and its `value`, `get`, and `set` properties,
+    if present, are debuggee values.)
+
+`getOwnPropertyNames()`
+:   Return an array of strings naming all the referent's own properties, as
+    if <code>Object.getOwnPropertyNames(<i>referent</i>)</code> had been
+    called in the debuggee, and the result copied in the scope of the
+    debugger's global object.
+
+<code>defineProperty(<i>name</i>, <i>attributes</i>)</code>
+:   Define a property on the referent named <i>name</i>, as described by
+    the property descriptor <i>descriptor</i>. Any `value`, `get`, and
+    `set` properties of <i>attributes</i> must be debuggee values. (This
+    function behaves like `Object.defineProperty`, except that the target
+    object is implicit, and in a different compartment from the function
+    and descriptor.)
+
+<code>defineProperties(<i>properties</i>)</code>
+:   Add the properties given by <i>properties</i> to the referent. (This
+    function behaves like `Object.defineProperties`, except that the target
+    object is implicit, and in a different compartment from the
+    <i>properties</i> argument.)
+
+<code>deleteProperty(<i>name</i>)</code>
+:   Remove the referent's property named <i>name</i>. Return true if the
+    property was successfully removed, or if the referent has no such
+    property. Return false if the property is non-configurable.
+
+`seal()`
+:   Prevent properties from being added to or deleted from the referent.
+    Return this `Debugger.Object` instance. (This function behaves like the
+    standard `Object.seal` function, except that the object to be sealed is
+    implicit and in a different compartment from the caller.)
+
+`freeze()`
+:   Prevent properties from being added to or deleted from the referent, and
+    mark each property as non-writable. Return this `Debugger.Object`
+    instance. (This function behaves like the standard `Object.freeze`
+    function, except that the object to be sealed is implicit and in a
+    different compartment from the caller.)
+
+`preventExtensions()`
+:   Prevent properties from being added to the referent. (This function
+    behaves like the standard `Object.preventExtensions` function, except
+    that the object to operate on is implicit and in a different compartment
+    from the caller.)
+
+`isSealed()`
+:   Return true if the referent is sealed—that is, if it is not extensible,
+    and all its properties have been marked as non-configurable. (This
+    function behaves like the standard `Object.isSealed` function, except
+    that the object inspected is implicit and in a different compartment
+    from the caller.)
+
+`isFrozen()`
+:   Return true if the referent is frozen—that is, if it is not extensible,
+    and all its properties have been marked as non-configurable and
+    read-only. (This function behaves like the standard `Object.isFrozen`
+    function, except that the object inspected is implicit and in a
+    different compartment from the caller.)
+
+`isExtensible()`
+:   Return true if the referent is extensible—that is, if it can have new
+    properties defined on it. (This function behaves like the standard
+    `Object.isExtensible` function, except that the object inspected is
+    implicit and in a different compartment from the caller.)
+
+<code>copy(<i>value</i>)</code>
+:   Apply the HTML5 "structured cloning" algorithm to create a copy of
+    <i>value</i> in the referent's global object (and thus in the referent's
+    compartment), and return a `Debugger.Object` instance referring to the
+    copy.
+
+    Note that this returns primitive values unchanged. This means you can
+    use `Debugger.Object.prototype.copy` as a generic "debugger value to
+    debuggee value" conversion function—within the limitations of the
+    "structured cloning" algorithm.
+
+<code>create(<i>prototype</i>, [<i>properties</i>])</code>
+:   Create a new object in the referent's global (and thus in the
+    referent's compartment), and return a `Debugger.Object` referring to
+    it. The new object's prototype is <i>prototype</i>, which must be an
+    `Debugger.Object` instance. The new object's properties are as given by
+    <i>properties</i>, as if <i>properties</i> were passed to
+    `Debugger.Object.prototype.defineProperties`, with the new
+    `Debugger.Object` instance as the `this` value.
+
+<code>makeDebuggeeValue(<i>value</i>)</code>
+:   Return the debuggee value that represents <i>value</i> in the debuggee.
+    If <i>value</i> is a primitive, we return it unchanged; if <i>value</i>
+    is an object, we return the `Debugger.Object` instance representing
+    that object, wrapped appropriately for use in this `Debugger.Object`'s
+    referent's compartment.
+
+    Note that, if <i>value</i> is an object, it need not be one allocated
+    in a debuggee global, nor even a debuggee compartment; it can be any
+    object the debugger wishes to use as a debuggee value.
+
+    As described above, each `Debugger.Object` instance presents its
+    referent as viewed from a particular compartment. Given a
+    `Debugger.Object` instance <i>d</i> and an object <i>o</i>, the call
+    <code><i>d</i>.makeDebuggeeValue(<i>o</i>)</code> returns a
+    `Debugger.Object` instance that presents <i>o</i> as it would be seen
+    by code in <i>d</i>'s compartment.
+
+<code>decompile([<i>pretty</i>])</code>
+:   If the referent is a function that is debuggee code, return the
+    JavaScript source code for a function definition equivalent to the
+    referent function in its effect and result, as a string. If
+    <i>pretty</i> is present and true, produce indented code with line
+    breaks. If the referent is not a function that is debuggee code, return
+    `undefined`.
+
+<code>call(<i>this</i>, <i>argument</i>, ...)</code>
+:   If the referent is callable, call it with the given <i>this</i> value
+    and <i>argument</i> values, and return a [completion value][cv]
+    describing how the call completed. <i>This</i> should be a debuggee
+    value, or `{ asConstructor: true }` to invoke the referent as a
+    constructor, in which case SpiderMonkey provides an appropriate `this`
+    value itself. Each <i>argument</i> must be a debuggee value. All extant
+    handler methods, breakpoints, watchpoints, and so on remain active
+    during the call. If the referent is not callable, throw a `TypeError`.
+    This function follows the [invocation function conventions][inv fr].
+
+<code>apply(<i>this</i>, <i>arguments</i>)</code>
+:   If the referent is callable, call it with the given <i>this</i> value
+    and the argument values in <i>arguments</i>, and return a
+    [completion value][cv] describing how the call completed. <i>This</i>
+    should be a debuggee value, or `{ asConstructor: true }` to invoke
+    <i>function</i> as a constructor, in which case SpiderMonkey provides
+    an appropriate `this` value itself. <i>Arguments</i> must either be an
+    array (in the debugger) of debuggee values, or `null` or `undefined`,
+    which are treated as an empty array. All extant handler methods,
+    breakpoints, watchpoints, and so on remain active during the call. If
+    the referent is not callable, throw a `TypeError`. This function
+    follows the [invocation function conventions][inv fr].
+
+<code>evalInGlobal(<i>code</i>, [<i>options</i>])</code>
+:   If the referent is a global object, evaluate <i>code</i> in that global
+    environment, and return a [completion value][cv] describing how it completed.
+    <i>Code</i> is a string. All extant handler methods, breakpoints,
+    watchpoints, and so on remain active during the call. This function
+    follows the [invocation function conventions][inv fr].
+    If the referent is not a global object, throw a `TypeError` exception.
+
+    <i>Code</i> is interpreted as strict mode code when it contains a Use
+    Strict Directive.
+
+    If <i>code</i> is not strict mode code, then variable declarations in
+    <i>code</i> affect the referent global object. (In the terms used by the
+    ECMAScript specification, the `VariableEnvironment` of the execution
+    context for the eval code is the referent.)
+
+    The <i>options</i> argument is as for [`Debugger.Frame.prototype.eval`][fr eval].
+
+<code>evalInGlobalWithBindings(<i>code</i>, <i>bindings</i>, [<i>options</i>])</code>
+:   Like `evalInGlobal`, but evaluate <i>code</i> using the referent as the
+    variable object, but with a lexical environment extended with bindings
+    from the object <i>bindings</i>. For each own enumerable property of
+    <i>bindings</i> named <i>name</i> whose value is <i>value</i>, include a
+    variable in the lexical environment in which <i>code</i> is evaluated
+    named <i>name</i>, whose value is <i>value</i>. Each <i>value</i> must
+    be a debuggee value. (This is not like a `with` statement: <i>code</i>
+    may access, assign to, and delete the introduced bindings without having
+    any effect on the <i>bindings</i> object.)
+
+    This method allows debugger code to introduce temporary bindings that
+    are visible to the given debuggee code and which refer to debugger-held
+    debuggee values, and do so without mutating any existing debuggee
+    environment.
+
+    Note that, like `evalInGlobal`, if the code passed to
+    `evalInGlobalWithBindings` is not strict mode code, then any
+    declarations it contains affect the referent global object, even as
+    <i>code</i> is evaluated in an environment extended according to
+    <i>bindings</i>. (In the terms used by the ECMAScript specification, the
+    `VariableEnvironment` of the execution context for non-strict eval code
+    is the referent, and the <i>bindings</i> appear in a new declarative
+    environment, which is the eval code's `LexicalEnvironment`.)
+
+    The <i>options</i> argument is as for [`Debugger.Frame.prototype.eval`][fr eval].
+
+`asEnvironment()`
+:   If the referent is a global object, return the [`Debugger.Environment`][environment]
+    instance representing the referent as a variable environment for
+    evaluating code. If the referent is not a global object, throw a
+    `TypeError`.
+
+<code>setObjectWatchpoint(<i>handler</i>)</code> <i>(future plan)</i>
+:   Set a watchpoint on all the referent's own properties, reporting events
+    by calling <i>handler</i>'s methods. Any previous watchpoint handler on
+    this `Debugger.Object` instance is replaced. If <i>handler</i> is null,
+    the referent is no longer watched. <i>Handler</i> may have the following
+    methods, called under the given circumstances:
+
+    <code>add(<i>frame</i>, <i>name</i>, <i>descriptor</i>)</code>
+    :   A property named <i>name</i> has been added to the referent.
+        <i>Descriptor</i> is a property descriptor of the sort accepted by
+        `Debugger.Object.prototype.defineProperty`, giving the newly added
+        property's attributes.
+
+    <code>delete(<i>frame</i>, <i>name</i>)</code>
+    :   The property named <i>name</i> is about to be deleted from the referent.
+
+    <code>change(<i>frame</i>, <i>name</i>, <i>oldDescriptor</i>, <i>newDescriptor</i>)</code>
+    :   The existing property named <i>name</i> on the referent is being changed
+        from those given by <i>oldDescriptor</i> to those given by
+        <i>newDescriptor</i>. This handler method is only called when attributes
+        of the property other than its value are being changed; if only the
+        value is changing, SpiderMonkey calls the handler's `set` method.
+
+    <code>set(<i>frame</i>, <i>oldValue</i>, <i>newValue</i>)</code>
+    :   The data property named <i>name</i> of the referent is about to have its
+        value changed from <i>oldValue</i> to <i>newValue</i>.
+
+        SpiderMonkey only calls this method on assignments to data properties
+        that will succeed; assignments to un-writable data properties fail
+        without notifying the debugger.
+
+    <code>extensionsPrevented(<i>frame</i>)</code>
+    :   The referent has been made non-extensible, as if by a call to
+        `Object.preventExtensions`.
+
+    For all watchpoint handler methods:
+
+    * Handler calls receive the handler object itself as the `this` value.
+
+    * The <i>frame</i> argument is the current stack frame, whose code is
+      about to perform the operation on the object being reported.
+
+    * If the method returns `undefined`, then SpiderMonkey makes the announced
+      change to the object, and continues execution normally. If the method
+      returns an object:
+
+    * If the object has a `superseded` property whose value is a true value,
+      then SpiderMonkey does not make the announced change.
+
+    * If the object has a `resume` property, its value is taken as a
+      [resumption value][rv], indicating how
+      execution should proceed. (However, `return` resumption values are not
+      supported.)
+
+    * If a given method is absent from <i>handler</i>, then events of that
+      sort are ignored. The watchpoint consults <i>handler</i>'s properties
+      each time an event occurs, so adding methods to or removing methods from
+      <i>handler</i> after setting the watchpoint enables or disables
+      reporting of the corresponding events.
+
+    * Values passed to <i>handler</i>'s methods are debuggee values.
+      Descriptors passed to <i>handler</i>'s methods are ordinary objects in
+      the debugger's compartment, except for `value`, `get`, and `set`
+      properties in descriptors, which are debuggee values; they are the sort
+      of value expected by `Debugger.Object.prototype.defineProperty`.
+
+    * Watchpoint handler calls are cross-compartment, intra-thread calls: the
+      call takes place in the same thread that changed the property, and in
+      <i>handler</i>'s method's compartment (typically the same as the
+      debugger's compartment).
+
+    The new watchpoint belongs to the [`Debugger`][debugger-object] instance to which this
+    `Debugger.Object` instance belongs; disabling the [`Debugger`][debugger-object] instance
+    disables this watchpoint.
+
+`clearObjectWatchpoint()` <i>(future plan)</i>
+:   Remove any object watchpoint set on the referent.
+
+<code>setPropertyWatchpoint(<i>name</i>, <i>handler</i>)</code> <i>(future plan)</i>
+:   Set a watchpoint on the referent's property named <i>name</i>, reporting
+    events by calling <i>handler</i>'s methods. Any previous watchpoint
+    handler on this property for this `Debugger.Object` instance is
+    replaced. If <i>handler</i> is null, the property is no longer watched.
+    <i>Handler</i> is as described for
+    `Debugger.Object.prototype.setObjectWatchpoint`, except that it does not
+    receive `extensionsPrevented` events.
+
+<code>clearPropertyWatchpoint(<i>name</i>)</code> <i>(future plan)</i>
+:   Remove any watchpoint set on the referent's property named <i>name</i>.
+
+`unwrap()`
+:   If the referent is a wrapper that this `Debugger.Object`'s compartment
+    is permitted to unwrap, return a `Debugger.Object` instance referring to
+    the wrapped object. If we are not permitted to unwrap the referent,
+    return `null`. If the referent is not a wrapper, return this
+    `Debugger.Object` instance unchanged.
+
+`unsafeDereference()`
+:   Return the referent of this `Debugger.Object` instance.
+
+    If the referent is an inner object (say, an HTML5 `Window` object),
+    return the corresponding outer object (say, the HTML5 `WindowProxy`
+    object). This makes `unsafeDereference` more useful in producing values
+    appropriate for direct use by debuggee code, without using [invocation functions][inv fr].
+
+    This method pierces the membrane of `Debugger.Object` instances meant to
+    protect debugger code from debuggee code, and allows debugger code to
+    access debuggee objects through the standard cross-compartment wrappers,
+    rather than via `Debugger.Object`'s reflection-oriented interfaces. This
+    method makes it easier to gradually adapt large code bases to this
+    Debugger API: adapted portions of the code can use `Debugger.Object`
+    instances, but use this method to pass direct object references to code
+    that has not yet been updated.