Re: documenting widgets was: release 0.4.1 bug triage

Tom Trenka wrote:
> 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.

Hmm, OK.

> 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).

Hmm, well if it doesn't work then we have to change it.  As usual, I 
don't care much either way but I want to have a standard that everyone 
follows.  (Here an inconsistency is especially bad since things declared 
in a base class's initializer will overwrite things declared in the 
subclass's prototype.)

I'm pretty sure that widget parameters (even array parameters) can be 
declared in the dojo.extend() part (proof left as an exercise to the 
reader). But yeah there is the shared array problem for plain properties.

I'm not familiar with templatePath/templateCssPath issue(s).  Can you 
give an example?

And actually, other examples would be good too. I stress the word 
"example".  Picture's worth a thousand words :-)