doc renaming - again
|
View:
New views
10 Messages
—
Rating Filter:
Alert me
|
 |
doc renaming - again
by Donald Anderson-3
::
Rate this Message:
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@... www: http://www.ddanderson.com |
|
|
Re: doc renaming - again
by P T Withington
::
Rate this Message:
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@... > www: http://www.ddanderson.com > > > |
|
|
Re: doc renaming - again
by Donald Anderson-3
::
Rate this Message:
Probably because I forgot them!
On Jul 24, 2008, at 10:38 AM, P T Withington wrote:
-- Don Anderson Java/C/C++, Berkeley DB, systems consultant voice: 617-547-7881 email: dda@... www: http://www.ddanderson.com |
|
|
Re: doc renaming - again
by P T Withington
::
Rate this Message:
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@... >>> www: http://www.ddanderson.com >>> >>> >>> >> > > > -- > > Don Anderson > Java/C/C++, Berkeley DB, systems consultant > > voice: 617-547-7881 > email: dda@... > www: http://www.ddanderson.com > > > |
|
|
Re: doc renaming - again
by David Temkin
::
Rate this Message:
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@... >>>> www: http://www.ddanderson.com >>>> >>>> >>>> >>> >> >> >> -- >> >> Don Anderson >> Java/C/C++, Berkeley DB, systems consultant >> >> voice: 617-547-7881 >> email: dda@... >> www: http://www.ddanderson.com >> >> >> > |
|
|
Re: doc renaming - again
by P T Withington
::
Rate this Message:
Succinct and correct.
On 2008-07-26, at 12:34EDT, 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@... >>>>> www: http://www.ddanderson.com >>>>> >>>>> >>>>> >>>> >>> >>> >>> -- >>> >>> Don Anderson >>> Java/C/C++, Berkeley DB, systems consultant >>> >>> voice: 617-547-7881 >>> email: dda@... >>> www: http://www.ddanderson.com >>> >>> >>> >> > |
|
|
Re: doc renaming - again
by Donald Anderson-3
::
Rate this Message:
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:
-- Don Anderson Java/C/C++, Berkeley DB, systems consultant voice: 617-547-7881 email: dda@... www: http://www.ddanderson.com |
|
|
Re: doc renaming - again
by David Temkin
::
Rate this Message:
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:
|
|
|
Re: doc renaming - again
by Donald Anderson-3
::
Rate this Message:
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:
|
dataset.webarchive (283K)