Author: lou
Date: 2007-10-25 02:28:29 -0700 (Thu, 25 Oct 2007)
New Revision: 7006
Modified:
openlaszlo/trunk/docs/src/developers/debugging.dbk
Log:
Change 20071024-lou-r by [EMAIL PROTECTED] on 2007-10-24 16:51:29 AST
in /Users/lou/src/svn/openlaszlo/trunk
for http://svn.openlaszlo.org/openlaszlo/trunk
Summary: provide example use of Debug.monitor and Debug.trace
New Features: provide new Example 50.3. Using Debug.monitor() and Debug.trace()
Bugs Fixed: LPP-4954
Technical Reviewer: (pending)
QA Reviewer: (pending)
Doc Reviewer: (pending)
Documentation: remove old static listing of Debug.monitor()
remove legacy code examples that the build ignored
Modified: openlaszlo/trunk/docs/src/developers/debugging.dbk
===================================================================
--- openlaszlo/trunk/docs/src/developers/debugging.dbk 2007-10-25 09:00:16 UTC
(rev 7005)
+++ openlaszlo/trunk/docs/src/developers/debugging.dbk 2007-10-25 09:28:29 UTC
(rev 7006)
@@ -26,11 +26,6 @@
<textobject><textdata fileref="debugging-$1.lzx"/></textobject>
</programlisting>
</example>
-<?example role="live-example"><title>The Debugger
window</title><programlisting
role="lzx-embednew"><filename>debugging-$1.lzx</filename><parameter/><code>
-<canvas height="150" debug="true"/>
-</code></programlisting><programlisting>
-<canvas height="150" debug="true"/>
-</programlisting><?lzx-edit programs/debugging-$1.lzx></example?>
<para>Debugging may cause the application to run more slowly, even if
the debugger window is not visible.</para>
@@ -48,11 +43,7 @@
<textobject><textdata fileref="programs/debugging-$2.lzx"/></textobject>
</programlisting>
</example>
-<?example role="live-example"><title>The <canvas> debug
attribute</title><programlisting
role="lzx-embednew"><filename>debugging-$2.lzx</filename><parameter/><code>
-<canvas height="150" debug="true"/>
-</code></programlisting><programlisting>
-<canvas height="150" debug="true"/>
-</programlisting><?lzx-edit programs/debugging-$2.lzx></example?>
+
</listitem></varlistentry><varlistentry><term>The "Debug"
button</term><listitem><para>Press the "Debug" button on the
<glossterm>developer console</glossterm> to request a copy of the application
with debugging enabled. This is equivalent to recompiling the application with
the <literal>debug="true"</literal>.</para>
<!-- remove para tags; para is not a legal child of term LI LPP-4636 9/3/2007
-->
<!-- <term><para>The <literal>debug</literal> query parameter</para></term> -->
@@ -86,23 +77,6 @@
<textobject><textdata fileref="programs/debugging-$3.lzx"/></textobject>
</programlisting>
</example>
-<?informalexample role="live-example"><programlisting
role="lzx-embednew"><filename>debugging-$3.lzx</filename><parameter/><code>
-<canvas debug="true" height="150">
- <handler name="oninit"><![CDATA[
- for (var i = 0; i > 10; i ++) {
- canvas.width();
- }
- ]]></handler>
-</canvas>
-</code></programlisting><programlisting>
-<canvas debug="true" height="150">
- <handler name="oninit"><![CDATA[
- for (var i = 0; i > 10; i ++) {
- canvas.width();
- }
- ]]></handler>
-</canvas>
-</programlisting><?lzx-edit programs/debugging-$3.lzx></informalexample?>
<para>Turning on runtime error checking makes an application bigger
and slower. You should only perform size and speed optimization on
@@ -125,21 +99,6 @@
<textobject><textdata fileref="programs/debugging-$4.lzx"/></textobject>
</programlisting>
</example>
-<?example role="live-example"><title>Logging to the
debugger</title><programlisting
role="lzx-embednew"><filename>debugging-$4.lzx</filename><parameter/><code>
-<canvas debug="true" height="150">
- <script>
- Debug.write('user code');
- </script>
- <button onclick="Debug.write('click', getMouse('x'))"/>
-</canvas>
-</code></programlisting><programlisting>
-<canvas debug="true" height="150">
- <script>
- Debug.write('user code');
- </script>
- <button onclick="Debug.write('click', getMouse('x'))"/>
-</canvas>
-</programlisting><?lzx-edit programs/debugging-$4.lzx></example?>
<para>Some object are <glossterm baseform="inspect">inspectable</glossterm>.
See <xref linkend="debugging.inspecting"/> for more about the inspect feature of
the debugger. See <xref linkend="debugging.debug-tostring"/> to see
@@ -287,21 +246,7 @@
<textobject><textdata fileref="programs/debugging-$5.lzx"/></textobject>
</programlisting>
</example>
-<?example role="live-example"><title>Two ways of calling
Debug.write</title><programlisting
role="lzx-embednew"><filename>debugging-$5.lzx</filename><parameter/><code>
-<canvas debug="true" height="150">
- <handler name="oninit">
- Debug.write('subviews: ' + canvas.subviews);
- Debug.write('subviews:', canvas.subviews);
- </handler>
-</canvas>
-</code></programlisting><programlisting>
-<canvas debug="true" height="150">
- <handler name="oninit">
- Debug.write('subviews: ' + canvas.subviews); <co id="N10239"/>
- Debug.write('subviews:', canvas.subviews); <co id="N10243"/>
- </handler>
-</canvas>
-</programlisting><?lzx-edit programs/debugging-$5.lzx></example?>
+
<calloutlist><callout arearefs="N10239"><para>The (only) argument to
<indexterm><primary><literal>Debug.write()</literal>
method</primary></indexterm><methodname>Debug.write()</methodname> is a string,
so the value of <literal>canvas.subviews</literal> is not
inspectable.</para></callout><callout arearefs="N10243"><para>The second
argument to <indexterm><primary><literal>Debug.write()</literal>
method</primary></indexterm><methodname>Debug.write()</methodname> is an
non-string Object, so it is inspectable.</para></callout></calloutlist>
<para/></section>
<section id="generate-bug-report">
@@ -331,7 +276,9 @@
<para>
The compiler will omit those statements when you compile without debugging.
</para>
-<para/></section></section><section
id="configuring-debugger"><title>Configuring the Debugger</title>
+<para/></section>
+
+<section id="configuring-debugger"><title>Configuring the Debugger</title>
<para/><section><title>Debugger Window Position</title>
<para>By default, the debugger comes up over the top left corner of your
@@ -427,7 +374,7 @@
<para/></section></section><section><title>Inspecting Warnings and
Errors</title>
<para>Warnings and Errors are 'inspectable'. If you click on them, you will
inspect the warning or error object. If backtracing is enabled, a backtrace
will be one of the properties of the object that you can inspect. Inspecting
the backtrace will reveal the recorded stack frames which record: the function
called, <literal>this</literal> and the arguments to the function.</para>
-<para/></section></section><section><title>Monitoring object properties</title>
+<para/></section></section><section><title>Monitoring and tracing object
properties</title>
<para><literal>Debug.monitor(who, what)</literal>: Takes an object and
property name
and will emit a 'monitor message' each time that property is
changed.
@@ -436,8 +383,15 @@
<literal>Debug.unmonitor(who, what)</literal>: Turns that off.
</para>
<para>
-A monitor message consists of a timestamp, the function that caused the
change, the object and property, and the old and new
-values. E.g.:</para>
+A monitor message consists of the function that caused the change, a
timestamp, the object and property, and the old and new
+values. The following example uses <literal>Debug.monitor()</literal> and
<literal>Debug.trace()</literal>:</para>
+<example role="live-example">
+ <title>Using Debug.monitor() and Debug.trace()</title>
+ <programlisting language="lzx">
+ <textobject><textdata fileref="programs/debug-mon-trace.lzx"/></textobject>
+ </programlisting>
+</example>
+<!-- replaced with live example. IORIO 24 oct 2007
<programlisting><literal>
MONITOR: [69227.23] LzLoader.initializeRequestObj: «LoadMovie#0|
__debugger.lzx (loaded)».valid: true -> true
MONITOR: [69265.36] LzLoader.initializeRequestObj: «LoadMovie#0|
__debugger.lzx (loaded)».loaded: true -> false
@@ -446,8 +400,27 @@
MONITOR: [69436.51] LzLoadQueue.makeRequest: «LoadMovie#0| __debugger.lzx
(initialized)».loading: false -> true
MONITOR: [69702.58] LzLoader.returnData: «LoadMovie#0| __debugger.lzx
(loading)».loaded: false -> true
</literal>
-</programlisting>
-<para/></section><section><title>Tracing and Backtracing</title>
+</programlisting> -->
+<para/>
+<para>As shown in this example:</para>
+<itemizedlist><listitem><para>
+<literal>Debug.monitor()</literal> monitors attribute modification. It gives
a timestamp on attribute modification,
+shows the function doing the modification and the old and new value.
+</para></listitem>
+<listitem><para>
+<literal>Debug.trace()</literal> traces method calls. It gives a timestamp on
function call, shows the call and arguments,
+and a timestamp on function exit, shows the return value.
+</para></listitem>
+
+</itemizedlist>
+<para>If backtracing is enabled, the trace and monitor messages also capture a
backtrace
+(which you can see by inspecting the message). Can be especially handy if
+you are trying to figure out who/what/when is calling a method or clobbering a
property.
+</para>
+
+</section>
+<!-- added id to section so we can link to here. IORIO 24 oct 2007 -->
+<section id="trace-backtrace"><title>Tracing and Backtracing</title>
<para>The debugger provides methods that allow you to see interactions between
parts of your application.</para>
<para/><section><title>Tracing</title>
<para>
_______________________________________________
Laszlo-checkins mailing list
[email protected]
http://www.openlaszlo.org/mailman/listinfo/laszlo-checkins
