Re: documenting widgets was: release 0.4.1 bug triage

Not all of them need to be converted, and the only real change is adding an initializer function, and moving everything but functions into it.

So probably yes, somewhere around an hour.

On 10/29/06, LiuCougar <liucougar@xxxxxxxxx> wrote:

On 10/29/06, Tom Trenka <ttrenka@xxxxxxxxx> wrote:
> Sorry, probably should have also said that I've got no problem helping out
> with that (moving property defs into an initializer); in fact, I could
> probably get most of it done in an hour or so, if you wanted.
it sounds to me a lot of work (there are more than 100 widgets in
svn). you can convert all of them in one hour?

> On 10/29/06, Tom Trenka < ttrenka@xxxxxxxxx> wrote:
> > 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
>
>
>


--
http://liucougar.scim-im.org
"People's characters are strengthened through struggle against
difficulties; they are weakened by comfort."
- Old Chinese adage
_______________________________________________
dojo-contributors mailing list
dojo-contributors@xxxxxxxxxxxxxxx
http://dojotoolkit.org/mailman/listinfo/dojo-contributors

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