Re: documenting widgets was: release 0.4.1 bug triage

On 10/28/06, Bill Keese <bill@xxxxxxxxxxxxxxx> wrote:

Sorry that the widget documentation instructions aren't written down in
the wiki, but see the italics part of this email thread for instructions
on documenting widget parameters and widget summary:

http://dojotoolkit.org/pipermail/dojo-contributors/2006-October/004578.html

I see.  The problem here though is still a major disconnect between the guys working on the doc system.  My understanding is that there's been some enhancement bugs filed against Neil and that his implementation will not be what you guys seem to expect.  (Once again, it has to do with the doc tool *not* becoming Dojo-specific; I think his plans are to be able to generate XML with the parser, which you can then add to for additional things like widget-specific stuff).

What it basically means is that there's a good possibility what you've done with widget comments won't be used, at least not the way you think it would.  Which sucks, because it means you've done extra work for no reason :(

(as I mentioned, it just says to follow the example in DomWidget.js)

>
> (btw, I'm also noticing in some widgets that there are still properties
> being created on the widget's prototype (in other words, on the object
> used with dojo.extend) and not the widget itself--i.e . there's no
> initializer function being defined.  I thought we fixed these already?)

The consensus is to declare widget parameters in the dojo.extend part.
By "consensus" I mean that that's the pattern that Alex set and we are
all following that pattern. Again, see the example from DomWidget.js above.

All of us are fallible and we all make mistakes from time to time.  dojo.extend mixes the passed object into the main object's prototype and not the object itself (as I'm sure you're aware); that means that everything is shared across created objects.  It's ok for functions but it most certainly is *not* ok for anything else (functions execute in the context of the object calling it, etc. etc.).

This leads to subtle bugs, some of which are extremely hard to catch without *really* thinking some things through.  The shared array problem was just one of them...half of the templatePath/templateCssPath et al issue is because those properties are set on the object's prototype and not the object itself (although there are other issues involved, like getting the CSS to be specific to an instance--but that's another can of worms).

We need to change this.  I understand you've all been following a standard but it doesn't help when the standard happens to be wrong.  The *only* things that should be defined with an extend are functions, just like when you write things using the standard JS practice.  Just because someone created a clever wrapping doesn't mean language rules can be ignored.

I guess we didn't discuss where to declare private properties (typically
with and underscore in front of their name); declaring those in the
initializer function has the advantage of dealing w/arrays correctly,
and hiding them from the doc parser.  But for anything that needs to be
doc'd we are putting it in the dojo.extend part.

Unfortunately that has nothing to do with docs :(

trt

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