[Laszlo-dev] For Review: Change 20070601-jgrandyw-V Summary: Update drawview.lzx to use new 'interface' tag, making it easy to generate refguide page

[Jim Grandy]

My apologies; I jumped the gun and check this in. I'll back it out or  
fix the case...

On Jun 2, 2007, at 12:12 PM, Max Carlson wrote:

> Not approved - there's a regression with bezierCurveTo() and your  
> change in swf - compare http://localhost:8080/legals-clean/lps/ 
> components/extensions/test/drawing.lzx?lzr=swf7 with http:// 
> localhost:8080/legals/lps/components/extensions/test/drawing.lzx? 
> lzr=swf7
>
> The heart on the right is boxy.  Also, this looks significantly  
> harder to maintain/understand/read than it was before.  Is there a  
> way we could post-process the docs instead of bending the code to  
> the doc tools?
>
Since one goal with rewriting the doc tools was to derive reference  
material directly from the code, I certainly agree with the  
principle. But I don't think it is realistic for us to expect the doc  
tools to cover *every* idiom that could be used in LZX. This is an  
example where the effort required is just not justified given that  
there are multiple different ways of structuring the code that would  
be fully supported.

Here are the issues I had with the old code:

1- Use of <switch> blocks to express runtime specificity. The current  
LZX doc tool doesn't handle runtime-specific code as well as the JS2  
version does, because 99% of the runtime-specific code is in  
JavaScript. Adding support is possible, but would be a stretch given  
the LZX tool is written in XSL (the JS2 tool is written in Java).

(Side note: once we are generating class declarations from LZX code  
in our compiler, the LZX doc tool can essentially go away -- if the  
tag compiler carries comments forward as well, then the JS2 doc tool  
is sufficient for all purposes.)

2- Runtime specificity for class members. If the DHTML and AS2  
versions of <drawview> obey the same interface, there should be a  
single place where that interface is declared. The doc tools  
shouldn't be an interface compliance enforcement mechanism -- they  
should just report what's there. We have a mechanism now for  
declaring interfaces, so we should use it in this case.

Solutions are:

1- Wait until the tag compiler emits class declarations, and run all  
code (with preserved comments) through the js2doc tool after  
preprocessing by the tag compiler. This may be harder than it sounds;  
Tucker and Henry will have to weigh in.

2- Restructure per Tucker's recommendations. This is what is checked  
in, but you feel it is less readable. I'd be interested in more  
details here.

3- Rewrite in pure JavaScript, and either support documenting .js  
files in the components, or move drawview into the LFC. Tucker  
objected to the latter, and the former requires more modifications to  
the doc tools.

Thoughts?

jim

> Jim Grandy wrote:
>> Change 20070601-jgrandyw-V by jgrandyw at jgrandy-mbp.local on  
>> 2007-06-01 15:13:22 PDT
>>     in /Users/jgrandyw/dev/svn/openlaszlo/branches/legals2
>>     for http://svn.openlaszlo.org/openlaszlo/branches/legals
>> Summary: Update drawview.lzx to use new 'interface' tag, making it  
>> easy to generate refguide page
>> New Features:
>> Bugs Fixed:LPP-4080 LPP-2059
>> Technical Reviewer: ptw
>> QA Reviewer: max
>> Doc Reviewer:
>> Documentation:
>> Release Notes:
>> Details: Restructure drawview.lzx to have a single <interface>  
>> defining
>> the public interface of the class, followed by JavaScript class
>> declarations for per-runtime implementation. A bit klunky, yes,  
>> but with a
>> small change to lzx2js2doc.xsl, gives us a very clean refguide  
>> page for
>> that class.
>> Tests:
>> Files:
>> M      docs/src/xsl/lzx2js2doc.xsl
>> M      lps/components/extensions/drawview.lzx
>> Changeset: http://svn.openlaszlo.org/openlaszlo/patches/20070601- 
>> jgrandyw-V.tar
>
> -- 
> Regards,
> Max Carlson
> OpenLaszlo.org