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
