Bug 10346194: Update docs to describe Debugger.Source.prototype.introductionScript and .introductionOffset as implemented. DONTBUILD r=ejpbruel

The only change to content here is that we implemented 'introductionOffset', not
'introductionScriptOffset'.
This commit is contained in:
Jim Blandy 2014-07-10 17:26:39 -07:00
parent 5ab3d3927f
commit e9fa986160

View File

@ -131,42 +131,42 @@ from its prototype:
* `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.
`introductionScript`, `introductionOffset`
: 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 `introductionOffset` 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.
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 `introductionOffset` 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`.
Since a `<script>` element parsed from a web page's original HTML was not
introduced by any scripted call, its source's `introductionScript` and
`introductionOffset` 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.
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].
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].