[Laszlo-dev] doc renaming - again

Donald Anderson dda at ddanderson.com
Wed Jul 30 15:57:37 PDT 2008 

Yes, this should now be in.  If tonight's build is good you should
be able to see it all tomorrow.  Let me know if you see any problems.

On Jul 30, 2008, at 2:44 PM, David Temkin wrote:

> 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
>>
>>
>>
>


--

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/8035fa7e/attachment-0001.html

More information about the Laszlo-dev mailing list