Re: New version of API tool up

I realize I'm late to this part but...

On Tuesday 24 October 2006 6:53 am, Tom Trenka wrote:
> Inline as a wake up (meaning before my first cup of joe)...
>

[ snip ]

> > On Oct 21, 2006, at 10:26 AM, Scott J. Miles wrote:
> >
> > Perhaps the "Class" heading would more properly be "Constructor". I
> > recognize that the executable portion of the constructor is
> > documented separately and that could be a source of confusion. I'm
> > not a fanatic, but I basically agree with sticking as close to JS
> > terminology as possible.
> >
> > It looks like 'initializer' functions are documented as
> > 'constructor' functions, but they are actually distinct. I suggest
> > initializers be documented as such. Yes, the distinction is subtle,
> > but I think it's a mistake to obscure it. dojo.lang.declare was
> > never intended (by me) to be a (leaky) abstraction, but as an
> > encapsulation of various tasks one would otherwise often be doing
> > the long way.
> >
> > Hmm, I'm not seeing any methods/etc inside "Plotter" at all, but
> > that's a separate issue.
>
> In fact, the Plotter is merely a container for different plotter
> functions.
>
> I'm basing the notion of "Class" on this style guide (which is
> possibly
>
> > superseded by something else?)
> > http://dojotoolkit.org/docs/js_style_guide.html
> > Naming Conventions: 2. Names representing types (classes) MUST be
> > nouns and written in UpperLower case:
> >
> > So in the ApiRef, if something is "UpperLower" case and has methods
> > attached to it, I call it a "Class".  If in "lowerUpper" case, it's
> > an "Object".
>
> OK.  In some ways then I was wrong to name the methods in Plotters as
> proper-cased...*but*...that's a style *guide*.  Which we are supposed
> to follow, true.  But I can tell you for sure that there is a whole
> body of people who have different ideas about what's right and
> wrong--and in particular, I'm thinking of the .NET crowd, who
> ProperCase everything.
>
> I think we need to figure out a better way of determining what a
> constructor is, and I have a feeling this is more Neil's area than
> Owen's.  I would actually prefer that we were explicit about it in
> the doc comments; it seems to me that we avoid a lot of different
> issues if we were to do something like that.

We're in a dynamic language. We don't get garuntees, and frankly if 
folks don't agree with our style guide, they won't (and shouldn't) be 
adding code to Dojo. When in Rome and all that.

Lastly, the whole point of the doc tool vs. other available options has 
always been that we can avoid writing everything twice. The whole DRY 
thing is the reason we did this, and going back on it for soemthing 
where convention is enough to disambiguate seems...strange.

-- 
Alex Russell
alex@xxxxxxxxxxx     A99F 8785 F491 D5FD 04D7 ACD9 4158 FFDF 2894 6876
alex@xxxxxxxxxxxxxxx BE03 E88D EABB 2116 CC49 8259 CF78 E242 59C3 9723

pgpodkB0e4RRX.pgp
Description: PGP signature

_______________________________________________
dojo-contributors mailing list
dojo-contributors@xxxxxxxxxxxxxxx
http://dojotoolkit.org/mailman/listinfo/dojo-contributors