[Laszlo-dev] doc renaming - again

Wed Jul 30 08:51:51 PDT 2008

Thanks for the comments.  I plan to do the changes in 3 parts:

First - I'll shortly all the docs to use lz.tagname or lz.ClassName as  
you describe,
and get the navbars in good shape.  There are no lfc changes here, so  
risk
is low.

Second - I'll publish names for the Service classes.  Currently they  
are declared
as e.g. LzTimerService and the doc renaming treats this as  
lz.TimerService (as you want).
But these class names have not yet been published in the code.

Third - the internal naming that tucker wants:
   $lzc$class_TimerService instead of LzTimerService.  This does not
affect doc appearance as doc will already show this as lz.TimerService.
However it will affect doc implementation (as we do simple Lz => lz.  
substituting).
The external effect is just to remove LzTimerService to address global  
namespace solution, yes?
I think this issue comes up with all class names (LzNode? LzCanvas?)  
so do we get
a real benefit of fixing one without the other?  I'd like to open a  
separate JIRA to track this
discussion.

On Jul 26, 2008, at 12:34 PM, David Temkin wrote:

> This looks good to me, with one addition/clarification:
>
> The name for all LFC classes that define tags should be lower-case,  
> to match the tag name. That is, use "lz.view" instead of  
> "lz.View" (or the deprecated "LzView").
>
> That way all tags, whether defined in the LFC or user-defined in  
> LZX, will have runtime objects that match their class names, within  
> the "lz" namespace.
>
> LFC classes that do *not* define tags should retain their current  
> CamelCase names, within "lz".
>
> To summarize, all objects that were formerly global, both classes  
> and singleton services, should be under "lz", and should be referred  
> to that way in the docs. All classes that define tags, whether user- 
> defined, defined in custom components, or defined in the LFC should  
> have class names that match the tag name, within the "lz" namespace.
>
> Tucker, please confirm.
>
> - D.
>
>
> On Jul 24, 2008, at 4:17 PM, P T Withington wrote:
>
>> David needs to be in the loop on this.  This is my understanding:
>>
>> For any class that implements a tag 'foo' there will be an entry  
>> `lz.foo` that returns that class.  E.g., <view> is implemented by  
>> `LzView` but that is deprecated, use `lz.view` instead.  This is  
>> simply a matter of fixing the documentation, because these entries  
>> already exist in `lz`.
>>
>> For any service class that defines a singleton service 'Service',  
>> we would _like_ there to be an entry `lz.Service`.  E.g., the timer  
>> service is currently defined by `LzTimerService` and instantiated  
>> as the singleton `LzTimer`.  What we would like is `lz.Timer` to be  
>> how you access the singleton, and `lz.TimerService` to be how you  
>> access the class.  This requires updating the LFC _and_ adjusting  
>> the documentation.  Since you can't say:
>>
>> class lz.TimerService {...
>>
>> this means you will have to say:
>>
>> class $lzc$class_TimerService {...
>>
>> lz.TimerService = $lzc$class_TimerService;
>>
>> For any other classes that are public in the LFC, we would like  
>> them to be also now accessed from `lz`.  The only one I can think  
>> of is LzEventable, which happens to show up in the doc.  This would  
>> need to be handled as above.
>>
>> If all of this sounds like a kludge, it is; just a smidge less than  
>> the previous kludge.  What we really want to do is to have a couple  
>> of namespaces, `lz` and `lzinternal` and put the LFC in  
>> `lzinternal` except for public API's which would be in `lz`.  The  
>> big issue there is retrofitting that into JS1 where the  
>> namespace(s) will presumably be represented by Object's and the  
>> compiler will have to magically translate `lz:foo` to `lz.foo`.
>>
>> On 2008-07-24, at 13:07EDT, Donald Anderson wrote:
>>
>>> Probably because I forgot them!
>>>
>>>
>>> On Jul 24, 2008, at 10:38 AM, P T Withington wrote:
>>>
>>>> For some reason, Mail is not showing me your attachments?
>>>>
>>>> On 2008-07-24, at 09:39EDT, Donald Anderson wrote:
>>>>
>>>>> Tucker -
>>>>>
>>>>> I'd like to pick up the ball again on the lz.classname stuff.
>>>>> I left it in a state that was probably incorrect, but didn't  
>>>>> really
>>>>> have a clear picture of the final goal - and I'll need your help
>>>>> to advance it.
>>>>>
>>>>> To make this easy, I'm attaching webloc
>>>>> files for a couple of 'typical' pages, maybe you can tell me  
>>>>> quickly
>>>>> what's clearly wrong and how to change it to get something at  
>>>>> least
>>>>> closer to the goal.  We can do by phone/IM if that's better.
>>>>> Much of the hard stuff (figuring out how to mod the doc pages)  
>>>>> is done,
>>>>> and once we have some general rules for the naming,
>>>>> it should be pretty easy to fix.  If there's no hard rule for  
>>>>> naming,
>>>>> or there might be exceptions, we could add a javadoc tag to
>>>>> the sources.
>>>>>
>>>>> Thanks.
>>>>>
>>>>> - Don
>>>>>
>>>>> --
>>>>>
>>>>> Don Anderson
>>>>> Java/C/C++, Berkeley DB, systems consultant
>>>>>
>>>>> voice: 617-547-7881
>>>>> email: dda at ddanderson.com
>>>>> www: http://www.ddanderson.com
>>>>>
>>>>>
>>>>>
>>>>
>>>
>>>
>>> --
>>>
>>> Don Anderson
>>> Java/C/C++, Berkeley DB, systems consultant
>>>
>>> voice: 617-547-7881
>>> email: dda at ddanderson.com
>>> www: http://www.ddanderson.com
>>>
>>>
>>>
>>
>

--

Don Anderson
Java/C/C++, Berkeley DB, systems consultant

voice: 617-547-7881
email: dda at ddanderson.com
www: http://www.ddanderson.com

-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://www.openlaszlo.org/pipermail/laszlo-dev/attachments/20080730/c41c38f8/attachment-0001.html