Re: documenting widgets was: release 0.4.1 bugtriage

This is not the sort of thing that needs a vote. We vote too much as  
it is. It's a very clear problem. If there was a vote, it would only  
be something like "Should we move strings out of dojo.extend since  
they're immutable?"

The other question to raise would be if the objects are _supposed_ to  
be shared among all widget instances.

-Neil

On Oct 29, 2006, at 12:54 PM, Scott J. Miles wrote:

> Please do not make any sweeping change like this without proper  
> debate or at least a vote.
>
> Regards,
> Scott J. Miles
> TurboAjax Group
> http://www.turboajax.com
>
>
> From: dojo-contributors-bounces@xxxxxxxxxxxxxxx [mailto:dojo- 
> contributors-bounces@xxxxxxxxxxxxxxx] On Behalf Of Tom Trenka
> Sent: Sunday, October 29, 2006 6:40 AM
> To: dojo dev.
> Subject: Re: documenting widgets was: [dojo-contributors] release  
> 0.4.1 bugtriage
>
> 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.
>
> trt
>
> 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
>
> --
> No virus found in this outgoing message.
> Checked by AVG Free Edition.
> Version: 7.1.408 / Virus Database: 268.13.17/505 - Release Date:  
> 10/27/2006
>
> _______________________________________________
> dojo-contributors mailing list
> dojo-contributors@xxxxxxxxxxxxxxx
> http://dojotoolkit.org/mailman/listinfo/dojo-contributors