Documentation: To auto-generate, or not to auto-generate?

[Anastasia Cheetham]

We recently decided that we would move to auto-generated API  
documentation produced from comments inline with the code (see  
discussion on the list titled "Autogenerated API documentation",  
started February 20, 2009).

I have been researching and playing with various tools for this, but I  
had a bit of an epiphany this afternoon, and I think we need to re- 
think this. I'd appreciate everyone's thoughts.


Our components are highly configurable - it is one of our primary  
strengths. This configurability means that we provide implementors  
with a variety of options for customizing a component. Explaining  
these options in documentation takes words - often, quite a number of  
them.

As an example, have a look at the List Reorderer API page:
     http://wiki.fluidproject.org/display/fluid/List+Reorderer+API
This is a relatively straight-forward component, with a typical amount  
of available customization.

Here's the crux of the problem I'm seeing:
If we want to be able to automatically generate a page that includes  
all of this information, then *all of this information will have to be  
in the comments of the JavaScript file*. I think that having this much  
text in the file will make it completely unreasonable to work with.

Additionally: The List Reorderer is one of several flavours of the  
Reorderer. Internally, all of the different flavours exist in a single  
JavaScript file. I can't even begin to imagine how we could coax an  
automated system into producing 5 different pages from a single file,  
each with different but overlapping subsets of the information. We  
would have to split the JavaScript itself up into multiple files, for  
a start.

And the Reorderer is not the only component that presents this issue.  
The Inline Edit has a number of configuration; the Uploader has  
several alternative subcomponents; the Pager has several alternative  
subcomponents...


My fear is that any automatically generated documentation will lose  
the cohesiveness that I think is a strength of what we've got now.

Does anyone have any suggestions??

-- 
Anastasia Cheetham                   a.cheetham at utoronto.ca
Software Designer, Fluid Project    http://fluidproject.org
Adaptive Technology Resource Centre / University of Toronto