Re: documenting widgets was: release 0.4.1 bug triage

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