Re: documenting widgets was: release 0.4.1 bug triage

Ok, so I talked with Neil a bit today, and I was told that the documentation efforts inside the widget code that I was pointed to isn't being parsed by the doc parser, and probably won't be.  (For the record, Bill pointed me at 
DatePicker.js as an example of widget documentation).  From this, I gather that there's been some private conversation about what kind of documentation is required in the code for the widget in question that itself hasn't been documented; I went searching on the Dojo wiki for instructions on what needs to be done and how, and found none--other than the original Code Documentation that Neil wrote.

My understanding from Neil is that he is trying to set up the parser system to be able to generate XML files, which can then be modified outside the parser system to include any additional information needed or wanted.

I don't have a problem contributing at some point to the actual Dojo book instructions and explanations on how to use the widgets I've written, but I don't want to be adding commentary to code that is going to be ignored or tossed because there was a jump of the gun.  Someone want to turn around and get our signals straight regarding API documentation?  

The first thing to understand (if I was understanding Neil correctly) is that the doc parser system *needs* to be Dojo agnostic (particularly with the interest that the Prototype folks are showing with it).  Added comments like I saw in the DatePicker widget are most certainly Dojo-specific, and based on the conversations I've seen going back and forth, it seems like there's a lot of somewhat selfish calls to add things to the parser (I'm using the term here not in a critical sense but an objective one, as in "can you add this so that this section of code could be easier to document" selfish--not the "me first" selfish)--and once again, there seems to be the attitude that "the build system will take care of all things" (
i.e. more comments please).

There needs to be a balance.  I don't really care where that balance point is (well, I do but only in terms of how much of it there is) but I would like it to be *decided on*.  I've already rewritten documentation 3 times for some modules that I own, and while I appreciate the need I feel that my time can be better spent on other things.

trt

(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?)

On 10/27/06, Bill Keese <bill@xxxxxxxxxxxxxxx> wrote:

yeah, you agreed to document all the widgets you owned.  is it done
already?  i didn't notice a checkin.  FilteringTable, Yahoo/Google maps,
Chart.  I filed a bug as http://trac.dojotoolkit.org/ticket/1781

Tom Trenka wrote:
> I'm signed up for widget docs?
>
> On 10/27/06, *Bill Keese* <bill@xxxxxxxxxxxxxxx
> <mailto: bill@xxxxxxxxxxxxxxx>> wrote:
>
>     Carla Mott wrote:
>      > Any idea when the API doc for widgets will be done?
>
>     My part will be done by Monday or Tuesday, but there are other people
>     signed up for widget doc too (Tom, Ilia, Neil R, Joose and Nicola) so
>     it's a really a group effort.  I put API doc on the agenda for the
>     meeting today (which, by the way, I may sleep through).
>     _______________________________________________
>     dojo-contributors mailing list
>     dojo-contributors@xxxxxxxxxxxxxxx
>     <mailto: dojo-contributors@xxxxxxxxxxxxxxx>
>     http://dojotoolkit.org/mailman/listinfo/dojo-contributors
>
>
>
> ------------------------------------------------------------------------
>
> _______________________________________________
> 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