diff -r 000000000000 -r 6474c204b198 js/src/doc/Debugger/Debugger.Source.md
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/js/src/doc/Debugger/Debugger.Source.md	Wed Dec 31 06:09:35 2014 +0100
@@ -0,0 +1,212 @@
+# Debugger.Source
+
+A `Debugger.Source` instance represents a piece of JavaScript source
+code: its properties provide the source code itself as a string, and
+describe where it came from. Each [`Debugger.Script`][script] instance refers to
+the `Debugger.Source` instance holding the source code from which it was
+produced.
+
+If a single piece of source code contains both top-level code and
+function definitions, perhaps with nested functions, then the
+[`Debugger.Script`][script] instances for those all refer to the same
+`Debugger.Source` instance. Each script indicates the substring of the
+overall source to which it corresponds.
+
+A `Debugger.Source` instance may represent only a portion of a larger
+source document. For example, an HTML document can contain JavaScript in
+multiple `<script>` elements and event handler content attributes.
+In this case, there may be either a single `Debugger.Source` instance
+for the entire HTML document, with each [`Debugger.Script`][script] referring to
+its substring of the document; or there may be a separate
+`Debugger.Source` instance for each `<script>` element and
+attribute. The choice is left up to the implementation.
+
+If a given piece of source code is presented to the JavaScript
+implementation more than once, with the same origin metadata, the
+JavaScript implementation may generate a fresh `Debugger.Source`
+instance to represent each presentation, or it may use a single
+`Debugger.Source` instance to represent them all.
+
+Each [`Debugger`][debugger-object] instance has a separate collection of `Debugger.Source`
+instances representing the source code that has been presented to the
+system.
+
+A debugger may place its own properties on `Debugger.Source` instances,
+to store metadata about particular pieces of source code.
+
+
+## Accessor Properties of the Debugger.Source Prototype Object
+
+A `Debugger.Source` instance inherits the following accessor properties
+from its prototype:
+
+`text`
+:   The JavaScript source code, as a string. The value satisfies the
+    `Program`, `FunctionDeclaration`, or `FunctionExpression` productions in
+    the ECMAScript standard.
+
+`enclosingStart` <i>(future plan)</i>
+:   The position within the enclosing document at which this source's text
+    starts. This is a zero-based character offset. (The length of this
+    script within the enclosing document is `source.length`.)
+
+`lineCount` <i>(future plan)</i>
+:   The number of lines in the source code. If there are characters after
+    the last newline in the source code, those count as a final line;
+    otherwise, `lineCount` is equal to the number of newlines in the source
+    code.
+
+`url`
+:   The URL from which this source was loaded, if this source was loaded
+    from a URL. Otherwise, this is `undefined`. Source may be loaded from a
+    URL in the following ways:
+
+    * The URL may appear as the `src` attribute of a `<script>` element
+      in markup text.
+
+    * The URL may be passed to the `Worker` web worker constructor, or the web
+      worker `importScripts` function.
+
+    * The URL may be the name of a XPCOM JavaScript module or subscript.
+
+    (Note that code passed to `eval`, the `Function` constructor, or a
+    similar function is <i>not</i> considered to be loaded from a URL; the
+    `url` accessor on `Debugger.Source` instances for such sources should
+    return `undefined`.)
+
+`element`
+:   The [`Debugger.Object`][object] instance referring to the DOM element to which
+    this source code belongs, if any, or `undefined` if it belongs to no DOM
+    element. Source belongs to a DOM element in the following cases:
+
+    * Source belongs to a `<script>` element if it is the element's text
+      content (that is, it is written out as the body of the `<script>`
+      element in the markup text), or is the source document referenced by its
+      `src` attribute.
+
+    * Source belongs to a DOM element if it is an event handler content
+      attribute (that is, if it is written out in the markup text as an
+      attribute value).
+
+    * Source belongs to a DOM element if it was assigned to one of the
+      element's event handler IDL attributes as a string. (Note that one may
+      assign both strings and functions to DOM elements' event handler IDL
+      attributes. If one assigns a function, that function's script's source
+      does <i>not</i> belong to the DOM element; the function's definition
+      must appear elsewhere.)
+
+    (If the sources attached to a DOM element change, the `Debugger.Source`
+    instances representing superceded code still refer to the DOM element;
+    this accessor only reflects origins, not current relationships.)
+
+`elementAttributeName`
+:   If this source belongs to a DOM element because it is an event handler
+    content attribute or an event handler IDL attribute, this is the name of
+    that attribute, a string. Otherwise, this is `undefined`.
+
+`introductionType`
+:   A string indicating how this source code was introduced into the system.
+    This accessor returns one of the following values:
+
+    * `"eval"`, for code passed to `eval`.
+
+    * `"Function"`, for code passed to the `Function` constructor.
+
+    * `"Worker"`, for code loaded by calling the Web worker constructor—the
+      worker's main script.
+
+    * `"importScripts"`, for code by calling `importScripts` in a web worker.
+
+    * `"eventHandler"`, for code assigned to DOM elements' event handler IDL
+      attributes as a string.
+
+    * `"scriptElement"`, for code belonging to `<script>` elements.
+
+    * `"javascriptURL"`, for code presented in `javascript:` URLs.
+
+    * `"setTimeout"`, for code passed to `setTimeout` as a string.
+
+    * `"setInterval"`, for code passed to `setInterval` as a string.
+
+    * `undefined`, if the implementation doesn't know how the code was
+      introduced.
+
+`introductionScript`, `introductionScriptOffset` <i>(future plan)</i>
+:   If this source was introduced by calling a function from debuggee code,
+    then `introductionScript` is the [`Debugger.Script`][script] instance referring to
+    the script containing that call, and `introductionScriptOffset` is the
+    call's bytecode offset within that script. Otherwise, these are both
+    `undefined`. Taken together, these properties indicate the location of
+    the introducing call.
+
+    For the purposes of these accessors, assignments to accessor properties
+    are treated as function calls. Thus, setting a DOM element's event
+    handler IDL attribute by assigning to the corresponding JavaScript
+    property creates a source whose `introductionScript` and
+    `introductionScriptOffset` refer to the property assignment.
+
+    Since a `<script>` element parsed from a web page's original HTML
+    was not introduced by any scripted call, its source's
+    `introductionScript` and `introductionScriptOffset` accessors both
+    return `undefined`.
+
+    If a `<script>` element was dynamically inserted into a document,
+    then these accessors refer to the call that actually caused the script
+    to run—usually the call that made the element part of the document.
+    Thus, they do <i>not</i> refer to the call that created the element;
+    stored the source as the element's text child; made the element a child
+    of some uninserted parent node that was later inserted; or the like.
+
+    Although the main script of a worker thread is introduced by a call to
+    `Worker` or `SharedWorker`, these accessors always return `undefined` on
+    such script's sources. A worker's main script source and the call that
+    created the worker are always in separate threads, but [`Debugger`][debugger-object] is an
+    inherently single-threaded facility: its debuggees must all run in the
+    same thread. Since the global that created the worker is in a different
+    thread, it is guaranteed not to be a debuggee of the [`Debugger`][debugger-object] instance
+    that owns this source; and thus the creating call is never "in debuggee
+    code". Relating a worker to its creator, and other multi-threaded
+    debugging concerns, are out of scope for [`Debugger`][debugger-object].
+
+
+
+## Function Properties of the Debugger.Source Prototype Object
+
+<code>substring(<i>start</i>, [<i>end</i>])</code> <i>(future plan)</i>
+:   Return a substring of this instance's `source` property, starting at
+    <i>start</i> and extending to, but not including, <i>end</i>. If
+    <i>end</i> is `undefined`, the substring returned extends to the end of
+    the source.
+
+    Both indices are zero-based. If either is `NaN` or negative, it is
+    replaced with zero. If either is greater than the length of the source,
+    it is replaced with the length of the source. If <i>start</i> is larger
+    than <i>end</i>, they are swapped. (This is meant to be consistent with
+    the way `String.prototype.substring` interprets its arguments.)
+
+<code>lineToPosition(<i>line</i>)</code> <i>(future plan)</i>
+:   Return an object of the form
+    <code>{ line:<i>line</i>, start:<i>start</i>, length:<i>length</i> }</code>, where
+    <i>start</i> is the character index within `source` of the first
+    character of line number <i>line</i>, and <i>length</i> is the length of
+    that line in characters, including the final newline, if any. The first
+    line is numbered one. If <i>line</i> is negative or greater than the
+    number of lines in this `Debugger.Source` instance, then return `null`.
+
+<code>positionToLine(<i>start</i>)</code> <i>(future plan)</i>
+:   Return an object of the form
+    <code>{ line:<i>line</i>, start:<i>start</i>, length:<i>length</i> }</code>, where
+    <i>line</i> is the line number containing the character position
+    <i>start</i>, and <i>length</i> is the length of that line in
+    characters, including the final newline, if any. The first line is
+    numbered one. If <i>start</i> is negative or greater than the length of
+    the source code, then return `null`.
+
+<code>findScripts(<i>query</i>)</code> <i>(future plan)</i>
+:   Return an array of [`Debugger.Script`][script] instances for all debuggee scripts
+    matching <i>query</i> that are produced from this `Debugger.Source`
+    instance. Aside from the restriction to scripts produced from this
+    source, <i>query</i> is interpreted as for
+    `Debugger.prototype.findScripts`.
+
+