Re: documenting widgets was: release 0.4.1 bug triage

Carla Mott wrote:
> Hi,
>
> I'd like to get clarification on documenting widgets.  If the 
> documentation is
> in the source file then is there a way to automatically generate 
> documentation
> for users that will be appropriate for the book?

It's certainly the intention to convert the widget code comments to a 
API web page, similar to javadoc; we just have quite gotten there yet. 
There's a disconnect between the way the parser is working now and the 
existing documentation in the widget source files.

See http://dojo.jot.com/WikiHome/DocParserInstructions for instructions.



> Since the book is a wiki there is, I think, an expectation that we can 
> and will update
> it any time during the development cycle.  If we can get the widget info
> that is in the source file in a format that is useful for the book then 
> great.  If
> not then I think we need to put that info in the book and work to keep 
> that up
> to date.

I'm pretty sure the plan is to have both the "latest" documentation, and 
a snapshot from each release available, both for the book, and for the 
api doc parsed out of the source files.

>  Regardless, I think there is additional info that should be 
> added such as
> examples.  I always thought that the API docs and the book complement each
> other.  Now I need to know what the API docs have so I can figure out what
> needs to be in the book.

Basically I think we are fighting over how to handle stuff like 
examples.  The three options are:
 1. write them in the source code like javadoc (actually some source 
code already has examples but they are getting kind of mangled w.r.t. 
newlines)
 2. put the examples in an XML file that stands alongside the 
javascript files, and is used (in conjunction with the javascript files) 
to generate the api doc
 3. write the examples in the book

Sorry, can't give a definitive answer cause it's not resolved.