[Laszlo-checkins] r11882 - in openlaszlo/trunk: WEB-INF/lps/lfc/compiler WEB-INF/lps/lfc/debugger WEB-INF/lps/lfc/debugger/platform/swf9 docs/src/nav
ptw@openlaszlo.org
ptw at openlaszlo.org
Tue Nov 25 10:53:15 PST 2008
Author: ptw
Date: 2008-11-25 10:53:11 -0800 (Tue, 25 Nov 2008)
New Revision: 11882
Modified:
openlaszlo/trunk/WEB-INF/lps/lfc/compiler/LzBootstrapDebugService.lzs
openlaszlo/trunk/WEB-INF/lps/lfc/compiler/LzFormatter.lzs
openlaszlo/trunk/WEB-INF/lps/lfc/compiler/LzMessage.lzs
openlaszlo/trunk/WEB-INF/lps/lfc/debugger/LzDebug.lzs
openlaszlo/trunk/WEB-INF/lps/lfc/debugger/LzMessage.lzs
openlaszlo/trunk/WEB-INF/lps/lfc/debugger/platform/swf9/LzBacktrace.as
openlaszlo/trunk/docs/src/nav/toc.xml
Log:
Change 20081125-ptw-K by ptw at dueling-banjos.home on 2008-11-25 10:05:21 EST
in /Users/ptw/OpenLaszlo/trunk
for http://svn.openlaszlo.org/openlaszlo/trunk
Summary: Document how to address the Debug console window in the new regime
Bugs Fixed:
LPP-7272 The debugger window (when it is in the application canvas) is no longer accessible as Debug
Technical Reviewer: hminsky (pending)
Doc Reviewer: lou at louiorio.com (pending)
Documentation:
If there were any places in the documentation where we implied
that Debug was equivalent to the debugger console window, they are
wrong.
Details:
*: mark lots of things private that I wish the doc tool
had not picked up. Fix lots of xref's.
LzDebug, LzBootstrapDebugService: Move documentation where it
belongs (and will be seen by the doctool). Create a dummy console
window class so you have a place to hang the documentation for the
<debug> tag (which controls the console window).
toc: Make an entry for <debug> separate from Debug.
Tests:
Inspection
Modified: openlaszlo/trunk/WEB-INF/lps/lfc/compiler/LzBootstrapDebugService.lzs
===================================================================
--- openlaszlo/trunk/WEB-INF/lps/lfc/compiler/LzBootstrapDebugService.lzs 2008-11-25 18:52:39 UTC (rev 11881)
+++ openlaszlo/trunk/WEB-INF/lps/lfc/compiler/LzBootstrapDebugService.lzs 2008-11-25 18:53:11 UTC (rev 11882)
@@ -4,9 +4,9 @@
* @copyright Copyright 2001-2008 Laszlo Systems, Inc. All Rights
* Reserved. Use is subject to license terms.
*
+ * @access public
* @topic LZX
* @subtopic Debugging
- * @access public
*/
@@ -16,8 +16,10 @@
* This interface defines the protocol between the debugger and the console
*
* @access private
+ *
+ * @devnote [2008-11-25 ptw] Should really just be an interface
*/
-/* interface */ class LzDebugConsole {
+class LzDebugConsole {
// Messages that will be displayed once a real console is
// instantiated. Messages are either LzMessage's that can be output
@@ -32,12 +34,12 @@
*
* @param msg: Will be coerced to a String if it is not
*
- * @ access private
+ * @access private
*/
function addText (msg) {};
/**
* Clears the console
- * @ access private
+ * @access private
*/
function clear () {};
/**
@@ -48,7 +50,7 @@
* @param Boolean newLine: whether to echo a trailing newline,
* default true
*
- * @ access private
+ * @access private
*/
function echo (str, newLine:Boolean=true) {};
/**
@@ -75,7 +77,7 @@
* @return String: the encoded representation (most likely as an
* HTML link).
*
- * @ access private
+ * @access private
*/
function makeObjectLink (rep:String, id, attrs=null):String { return undefined; };
/**
@@ -281,10 +283,14 @@
*/
var uncaughtBacktraceStack:*;
+ /** @access private */
var log_all_writes:Boolean = false;
+ /** @access private */
var logger:LzBootstrapDebugLogger;
+ /** @access private */
var console:LzDebugConsole;
+ /** @access private */
function LzBootstrapDebugService (logger:LzBootstrapDebugLogger=null,
console:LzDebugConsole=null) {
if (logger == null) {
@@ -442,93 +448,22 @@
}
};
+ /** @access private */
LzBootstrapDebugService.prototype._dbg_name = function () {
if (this === Debug) { return '#Debug'; } else return null;
}
};
-/**
- * <p>There are three ways to enable the debugger, as described in
- * the <a
- * href="${dguide}debugging.html#enabling-the-debugger">Debugging</a>
- * chapter of the Developer's Guide.</p>
- *
- * <p>The debugger can be useful in debugging your own code, but you
- * should also use debugging to report bugs. The debugger method
- * <xref linkend="Debug+debug.bugReport"/> will output information
- * that can be cut and pasted into a bug report to aid in
- * diagnosing the bug.</p>
- *
- * <p>The debugger has a range of methods for formatting output to the
- * debugger console:
- * <xref linkend="Debug+debug.debug"/>,
- * <xref linkend="Debug+debug.info"/>,
- * <xref linkend="Debug+debug.warn"/>, and
- * <xref linkend="Debug+debug.error"/>.
- * Each of these is based upon the basic formatted output method
- * <xref linkend="Debug+debug.format"/>. The variants prefix their
- * message with a label (DEBUG, INFO, WARNING, or ERROR) and will
- * print in a distinct color. When backtraces are enabled, these
- * debug messages will also give a source location.</p>
- *
- * <p>The debug messages can be silenced by setting
- * <xref linkend="Debug+debug.messageLevel"/>.</p>
- *
- * <p>Debugger messages are <em>inspectable</em>, as the example below
- * demonstrates. Clicking on the printed representation of the
- * object (in blue) will show the details of the object. The
- * message itself can also be inspected. When backtraces are
- * enabled, one component of the message will be a backtrace that
- * can be inspected to see the call chain and function arguments
- * that resulted in the message.</p>
- *
- * <example title="Debug output methods"><programlisting><![CDATA[
- * <canvas debug="true" height="150">
- * <debug width="350" height="90%" x="5" y="5" fontsize="8"/>
- * <script>
- * Debug.format("Hello %s!", 'world');
- * Debug.debug("Click there -> %w to inspect the object", {a: 1, b: 2});
- * </script>
- * </canvas>]]>
- * </programlisting></example>
- *
- * <p>The debugger can be used to trace method calls using
- * <xref linkend="Debug+debug.trace"/>
- * and it can be used to monitor instance variables using
- * <xref linkend="Debug+debug.monitor"/></p>
- *
- * <example title="Debug tracing and monitoring"><programlisting><![CDATA[
- * <canvas debug="true" height="150">
- * <debug width="350" height="90%" x="5" y="5" fontsize="8"/>
- * <script>
- * var o = {a: 7, f: function (x) { return x * x;}};
- * Debug.monitor(o, 'a');
- * o.a = 42;
- * Debug.trace(o, 'f');
- * o.f(4);
- * </script>
- * </canvas>]]>
- * </programlisting></example>
- *
- * <p>The optional <code>debug</code> tag controls the
- * appearance of the debugger when debugging is on. It does not
- * cause the application to be compiled with debugging mode enabled.
- * By default, the debug window will be sized to fit the lower 1/2
- * of the canvas, and can be resized as necessary.</p>
- *
- * @shortdesc The Laszlo debugger
- * @lzxname debug
- * @keywords private_constructor
- * @access public
- * @topic LZX
- * @subtopic Debugging
- *
+/***
* @devnote As soon as we have the LzBootstrapDebugService, we install it.
* This will get overridden by the full debugger when it loads
+ *
+ * @access private
*/
if ($as3) {
// We don't do the bootstrapping rebinding in as3
} else {
+ /** @access private */
var Debug = new LzBootstrapDebugService();
}
Modified: openlaszlo/trunk/WEB-INF/lps/lfc/compiler/LzFormatter.lzs
===================================================================
--- openlaszlo/trunk/WEB-INF/lps/lfc/compiler/LzFormatter.lzs 2008-11-25 18:52:39 UTC (rev 11881)
+++ openlaszlo/trunk/WEB-INF/lps/lfc/compiler/LzFormatter.lzs 2008-11-25 18:53:11 UTC (rev 11882)
@@ -13,8 +13,8 @@
* Formatted output support
*
* <p>See <xref linkend="LzText" />s <xref
- * linkend="LzText.prototype.format" /> and <xref linkend="Debug+debug"
- * />s <xref linkend="Debug+debug.format" /> methods for
+ * linkend="LzText.prototype.format" /> and <xref linkend="LzDebugService+debug"
+ * />s <xref linkend="LzDebugService+debug.prototype.format" /> methods for
* examples of how to present formatted text to the user
* interface.</p>
*
@@ -134,8 +134,8 @@
* specifier `w` that formats the argument as if by `Debug.__String`
* with the 'pretty'. If alternate format is requested (#), `w` uses the
* full `Debug.__String` format used by <xref
- * linkend="Debug+debug.write"/>. `%w` format obeys <xref
- * linkend="Debug+debug.printLength"/>. If a precision is specified,
+ * linkend="LzDebugService+debug.prototype.write"/>. `%w` format obeys <xref
+ * linkend="LzDebugService+debug.__ivars__.printLength"/>. If a precision is specified,
* that is used as printLength.
*
* When used to format a Debugger message, any Object that is
@@ -156,7 +156,7 @@
* feature).
*
* @devnote For backwards compatibility with <xref
- * linkend="Debug+debug.write"/>, if control is not a string or
+ * linkend="LzDebugService+debug.prototype.write"/>, if control is not a string or
* control has no formatting directives but there are multiple
* arguments, all the arguments are emitted separated by spaces.
*/
Modified: openlaszlo/trunk/WEB-INF/lps/lfc/compiler/LzMessage.lzs
===================================================================
--- openlaszlo/trunk/WEB-INF/lps/lfc/compiler/LzMessage.lzs 2008-11-25 18:52:39 UTC (rev 11881)
+++ openlaszlo/trunk/WEB-INF/lps/lfc/compiler/LzMessage.lzs 2008-11-25 18:53:11 UTC (rev 11882)
@@ -141,6 +141,7 @@
// we don't need to do this bootstrapping rebinding of LzMessage in as3, LzMessage is declared in
// debugger/LzMessage.lzs
} else {
+ /** @access private */
class LzMessage extends LzBootstrapMessage {
function LzMessage (message:String=null) {
super(message);
@@ -154,6 +155,7 @@
}
}
} else {
+ /** @access private */
var LzMessage = LzBootstrapMessage;
}
Modified: openlaszlo/trunk/WEB-INF/lps/lfc/debugger/LzDebug.lzs
===================================================================
--- openlaszlo/trunk/WEB-INF/lps/lfc/debugger/LzDebug.lzs 2008-11-25 18:52:39 UTC (rev 11881)
+++ openlaszlo/trunk/WEB-INF/lps/lfc/debugger/LzDebug.lzs 2008-11-25 18:53:11 UTC (rev 11882)
@@ -15,6 +15,7 @@
*/
global._dbg_name = 'global';
+
/**
** Generic DebugService
**/
@@ -23,9 +24,78 @@
* <p><code>Debug</code> is the single instance of the class
* <code>lz.DebugService</code>.</p>
*
- * <p></p>
+ * <p>There are three ways to enable the debugger, as described in
+ * the <a
+ * href="${dguide}debugging.html#enabling-the-debugger">Debugging</a>
+ * chapter of the Developer's Guide.</p>
*
+ * <p>The debugger can be useful in debugging your own code, but you
+ * should also use debugging to report bugs. The debugger method
+ * <xref linkend="LzDebugService+debug.prototype.bugReport"/> will output information
+ * that can be cut and pasted into a bug report to aid in
+ * diagnosing the bug.</p>
+ *
+ * <p>The debugger has a range of methods for formatting output to the
+ * debugger console:
+ * <xref linkend="LzDebugService+debug.prototype.debug"/>,
+ * <xref linkend="LzDebugService+debug.prototype.info"/>,
+ * <xref linkend="LzDebugService+debug.prototype.warn"/>, and
+ * <xref linkend="LzDebugService+debug.prototype.error"/>.
+ * Each of these is based upon the basic formatted output method
+ * <xref linkend="LzDebugService+debug.prototype.format"/>. The variants prefix their
+ * message with a label (DEBUG, INFO, WARNING, or ERROR) and will
+ * print in a distinct color. When backtraces are enabled, these
+ * debug messages will also give a source location.</p>
+ *
+ * <p>The debug messages can be silenced by setting
+ * <xref linkend="LzDebugService+debug.__ivars__.messageLevel"/>.</p>
+ *
+ * <p>Debugger messages are <em>inspectable</em>, as the example below
+ * demonstrates. Clicking on the printed representation of the
+ * object (in blue) will show the details of the object. The
+ * message itself can also be inspected. When backtraces are
+ * enabled, one component of the message will be a backtrace that
+ * can be inspected to see the call chain and function arguments
+ * that resulted in the message.</p>
+ *
+ * <example title="Debug output methods"><programlisting><![CDATA[
+ * <canvas debug="true" height="150">
+ * <debug y="5%" height="90%" />
+ * <script>
+ * Debug.format("Hello %s!\n", 'world');
+ * Debug.debug("Click there -> %w to inspect the object", {a: 1, b: 2});
+ * </script>
+ * </canvas>]]>
+ * </programlisting></example>
+ *
+ * <p>The debugger can be used to trace method calls using
+ * <xref linkend="LzDebugService+debug.prototype.trace"/>
+ * and it can be used to monitor instance variables using
+ * <xref linkend="LzDebugService+debug.prototype.monitor"/></p>
+ *
+ * <example title="Debug tracing and monitoring"><programlisting><![CDATA[
+ * <canvas debug="true" height="150">
+ * <debug y="5%" height="90%" />
+ * <script>
+ * var o = {a: 7, f: function (x) { return x * x;}};
+ * Debug.monitor(o, 'a');
+ * o.a = 42;
+ * Debug.trace(o, 'f');
+ * o.f(4);
+ * </script>
+ * </canvas>]]>
+ * </programlisting></example>
+ *
+ * <p>The optional <xref linkend="LzDebugConsoleWindow+debug"/> tag controls the appearance of
+ * the debugger console window when debugging is on.</p>
+ *
+ * @shortdesc The Laszlo debugger
+ * @keywords private_constructor
* @access public
+ * @topic LZX
+ * @subtopic Debugging
+ *
+ * @access public
*/
dynamic class LzDebugService extends LzBootstrapDebugService with LzFormatter {
/**
@@ -120,6 +190,8 @@
* Attaches the real debug console once it is available, and replays
* any messages saved in the bootstrap console. Typically called
* from makeDebugWindow
+ *
+ * @access private
*/
function attachDebugConsole (console:LzDebugConsole) {
var old = this.console;
@@ -265,7 +337,7 @@
/**
* Display one or more objects on the debug console.
*
- * Note: <xref linkend="Debug+debug.format"/> allows more control
+ * Note: <xref linkend="LzDebugService+debug.prototype.format"/> allows more control
* over displaying multiple objects. Use it instead of
* Debug.write.
*
@@ -273,9 +345,9 @@
* an informative format. Simple objects are represented as
* themselves. Printed Complex objects are represented by their type
* and a concise description. Long representations (and long Strings)
- * are abbreviated if they are longer than <xref linkend="Debug+debug.printLength"/>. Complex
+ * are abbreviated if they are longer than <xref linkend="LzDebugService+debug.__ivars__.printLength"/>. Complex
* objects and abbreviated objects presented as links. Clicking on
- * the link will invoke <xref linkend="Debug+debug.inspect"/> on the object,
+ * the link will invoke <xref linkend="LzDebugService+debug.prototype.inspect"/> on the object,
* giving more detail.
*
* @param Array * any: One or more values to display. Multiple
@@ -314,11 +386,9 @@
/**
* warnInternal tracks recursion and silences messages below
* messageLevel
+ *
+ * @access private
*/
- /**
- * warnInternal tracks recursion and silences messages below
- * messageLevel
- */
function warnInternal (xtor:Class, control:String, ...args) {
var sourceMessage = LzSourceMessage;
var level = sourceMessage.level
@@ -347,7 +417,7 @@
* Display a warning message on the console.
*
* Formats its arguments using <xref linkend="LzFormatter.prototype.formatToString"/>.
- * May be silenced by setting <xref linkend="Debug+debug.messageLevel"/>.
+ * May be silenced by setting <xref linkend="LzDebugService+debug.__ivars__.messageLevel"/>.
*
* @param string control: A control string where % indicates a
* subsequent argument is to be substituted
@@ -363,7 +433,7 @@
* Display an error message on the console.
*
* Formats its arguments using <xref linkend="LzFormatter.prototype.formatToString"/>.
- * May be silenced by setting <xref linkend="Debug+debug.messageLevel"/>.
+ * May be silenced by setting <xref linkend="LzDebugService+debug.__ivars__.messageLevel"/>.
*
* @param string control: A control string where % indicates a
* subsequent argument is to be substituted
@@ -379,7 +449,7 @@
* Display an informational message on the console.
*
* Formats its arguments using <xref linkend="LzFormatter.prototype.formatToString"/>.
- * May be silenced by setting <xref linkend="Debug+debug.messageLevel"/>.
+ * May be silenced by setting <xref linkend="LzDebugService+debug.__ivars__.messageLevel"/>.
*
* @param string control: A control string where % indicates a
* subsequent argument is to be substituted
@@ -395,7 +465,7 @@
* Display a debugging message on the console.
*
* Formats its arguments using <xref linkend="LzFormatter.prototype.formatToString"/>.
- * May be silenced by setting <xref linkend="Debug+debug.messageLevel"/>.
+ * May be silenced by setting <xref linkend="LzDebugService+debug.__ivars__.messageLevel"/>.
*
* @param string control: A control string where % indicates a
* subsequent argument is to be substituted
@@ -1542,3 +1612,47 @@
var __LzDebug = Debug;
}
+/**
+ * <p>The optional <code>debug</code> tag controls the appearance of
+ * the debugger console when debugging is on. It does <em>not</em>
+ * cause the application to be compiled with debugging mode enabled.
+ * By default, the debug console will appear as a <code>view</code> in
+ * the application canvas, sized to fit the lower 1/2 of the canvas.
+ * The usual <code>view</code> attributes can be used to size and
+ * position the debug console window. If you need to programmatically
+ * control the debug console window, use the <code>name</code>
+ * attribute:</p>
+ *
+ * <example title="Controlling the Debug console window"><programlisting><![CDATA[
+ * <canvas debug="true" height="150">
+ * <debug name="debugwindow" y="${button.y + button.height}" height="80%" />
+ * <button name="button">
+ * <attribute name="visible" value="${canvas['debugwindow'] != null}" />
+ * <attribute name="text"
+ value="${canvas['debugwindow']?((canvas.debugwindow.visible?'hide':'show') + ' debugger'):null}" />
+ * <handler name="onclick">
+ * canvas.debugwindow.setAttribute('visible', (! canvas.debugwindow.visible));
+ * </handler>
+ * </button>
+ * </canvas>
+ * ]]></programlisting></example>
+ *
+ * <p>Note the conditionalization testing whether the named window
+ * exists or not. The <code>debug</code> tag will <em>not</em> create
+ * a window in the application canvas if remote or console debugging
+ * is enabled.</p>
+ *
+ * @shortdesc Controlling the Laszlo debugger console window
+ * @lzxname debug
+ * @keywords private_constructor
+ * @access public
+ * @topic LZX
+ * @subtopic Debugging
+ *
+ * @access public
+ *
+ * @devnote [2008-1-25 ptw] This is a dummy class, here only for
+ * documentation purposes.
+ */
+class LzDebugConsoleWindow extends LzView {
+};
Modified: openlaszlo/trunk/WEB-INF/lps/lfc/debugger/LzMessage.lzs
===================================================================
--- openlaszlo/trunk/WEB-INF/lps/lfc/debugger/LzMessage.lzs 2008-11-25 18:52:39 UTC (rev 11881)
+++ openlaszlo/trunk/WEB-INF/lps/lfc/debugger/LzMessage.lzs 2008-11-25 18:53:11 UTC (rev 11882)
@@ -209,20 +209,23 @@
};
if ($as3) {
+ /** @access private */
class LzMessage extends LzDebugMessage {
function LzMessage (message=null) {
super(message);
}
- /**
- * Propagate this
- * @access private
- */
- static var xmlEscape = LzBootstrapMessage.xmlEscape;
+ /**
+ * Propagate this
+ * @access private
+ */
+ static var xmlEscape = LzBootstrapMessage.xmlEscape;
}
-
-} else {/**
+} else {
+/**
* Replace the bootstrap message with the more full-featured debug message
+ *
+ * @access private
*/
var LzMessage = LzDebugMessage;
}
Modified: openlaszlo/trunk/WEB-INF/lps/lfc/debugger/platform/swf9/LzBacktrace.as
===================================================================
--- openlaszlo/trunk/WEB-INF/lps/lfc/debugger/platform/swf9/LzBacktrace.as 2008-11-25 18:52:39 UTC (rev 11881)
+++ openlaszlo/trunk/WEB-INF/lps/lfc/debugger/platform/swf9/LzBacktrace.as 2008-11-25 18:53:11 UTC (rev 11882)
@@ -11,6 +11,7 @@
* @subtopic Debugging
*/
+/** @access private */
class LzBacktrace {
// just a placeholder for swf9
}
Modified: openlaszlo/trunk/docs/src/nav/toc.xml
===================================================================
--- openlaszlo/trunk/docs/src/nav/toc.xml 2008-11-25 18:52:39 UTC (rev 11881)
+++ openlaszlo/trunk/docs/src/nav/toc.xml 2008-11-25 18:53:11 UTC (rev 11882)
@@ -287,6 +287,7 @@
<category title="Development">
<item title="Debug" href="lz.DebugService+debug.html"/>
+ <item title="&lt;debug&gt;" href="lz.debug+debug.html"/>
<item title="&lt;SyncTester&gt;" href="lz.SyncTester.html" />
<item title="&lt;Test&gt;" href="lz.Test.html" />
<item title="&lt;TestCase&gt;" href="lz.TestCase.html" />
More information about the Laszlo-checkins
mailing list