[Laszlo-dev] For Review: Change 20081204-ptw-5 Summary: Improve formatToString documentation and examples

[P T Withington]

On 2008-12-06, at 08:09EST, Lou Iorio wrote:

> approved, but a few issues:
>
> LzFormatter:
>
> The first line on the page, "Formatted output support " should be a  
> shortdesc,
> not a <p>.

Will do.

> I find the example on positional arguments a little confusing.
>
> It seems to me that "last after first" in the output should be "last  
> before first".
>
> How about:
>
> <canvas layout="axis: y; spacing: 10" height="80" width="100%">
>  <debug y="5%" height="90%" />
>  <script>
>    var date = {us: "%1$s, %2$s", eu: "%2$s, %1$s"};
>  </script>
>  <text oninit="this.format(date.us, 'month', 'day')" />
>  <text oninit="this.format(date.eu, 'month', 'day');"/>
> </canvas>

Thank you!  My imagination was really sagging.  This is a much more  
compelling example.

> In the formatToString() method:
>
> There is a hyperlink with the text "Unix printf(3)" that seems to  
> want to open
> a man page. This, on the mac at least, does not work.

Maybe not _your_ mac.  Works for me!  I don't know what to do here --  
this is an experimental URL scheme (x-man-page), which probably won't  
work in most places.  The alternative is to have no link at all.  I  
don't know of any permanent place on the web to reference, so I  
thought maybe this link will help a few people.

> In the description for the parameter args, it mentions LzMessage,  
> but LzMessage
> is private, and there is no doc for it.

Can you file a bug?

> LzDebugservice has a couple of broken xrefs:

That's another bug.  Debug.monitor and Debug.trace are not documented.

> The debugger can be used to trace method calls using ??? and it can  
> be used to monitor instance variables using ???
>
>
> On Dec 5, 2008, at 3:01 PM, P T Withington wrote:
>
>> [Checking in so you can review.]
>>
>> Change 20081204-ptw-5 by ptw at dueling-banjos.home on 2008-12-04  
>> 13:51:43 EST
>>   in /Users/ptw/OpenLaszlo/trunk
>>   for http://svn.openlaszlo.org/openlaszlo/trunk
>>
>> Summary: Improve formatToString documentation and examples
>>
>> Bugs Fixed:
>> LPP-7437  Emphasize Debug.debug over Debug.write in documentation  
>> examples (partial)
>>
>> Technical Reviewer: lou at louiorio.com (pending)
>>
>> Details:
>>   LzMessage, LzDebug, LzMonitor, LzTrace, LzText: Update type
>>   declarations to something the doc tool will grok
>>
>>   LzDebug, LzText, LzFormatter: Update links to instance variables
>>   since the doc tool does not know what to do with an xref.
>>
>>   LzNode, LzText: Add missing private declarations
>>
>>   LzFormatter: Add examples suggested in bug report.  Improve the
>>   documentation of formatToString.  Make formatToString not complain
>>   about extra arguments when using positional arguments.
>>
>>   debugger/library: Remove <>'s that were making the doc tool
>>   whine.  Improve the documentation to make it clearer that there
>>   will not always be a debugger console window that you can
>>   manipulate.
>>
>> Tests:
>>   smokecheck, examples from bug, ant doc and inspection
>>
>> Files:
>> M      WEB-INF/lps/lfc/debugger/LzMessage.lzs
>> M      WEB-INF/lps/lfc/debugger/LzDebug.lzs
>> M      WEB-INF/lps/lfc/debugger/LzMonitor.lzs
>> M      WEB-INF/lps/lfc/debugger/LzTrace.lzs
>> M      WEB-INF/lps/lfc/core/LzNode.lzs
>> M      WEB-INF/lps/lfc/views/LzText.lzs
>> M      WEB-INF/lps/lfc/compiler/LzFormatter.lzs
>> M      lps/components/debugger/library.lzx
>>
>> Changeset: http://svn.openlaszlo.org/openlaszlo/patches/20081204-ptw-5.tar
>