[Laszlo-dev] doc renaming - again

Wed Jul 30 11:44:13 PDT 2008

Don,

Sounds good. Please confirm that tags defined in the LFC are actually  
declared as lower case names, as in "lz.tagname". I didn't think this  
was in.

- D.

On Jul 30, 2008, at 8:51 AM, Donald Anderson wrote:

> 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/6fdf5155/attachment-0001.html