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

[antranig at caret.cam.ac.uk]

I feel that although auto-generated documentation can, as you say,
never be an adequate replacement for a complete manually written
component guide, it is no reason not to have some. Yes, the
documentation of lots of frameworks that have only auto-generated
stuff frequently looks extremely shoddy, but I think it does fill
a need - especially for non-component oriented parts of the framework
like Fluid.js, keyboard-a11y etc.
Naturally for areas of the framework with more complex configuration,
such as Reorderer, Pager and Renderer, this will have to be supplemented
with a good deal of detailed presentation and explanation of the
meaning of their options and their interactions... I don't think
anyone is suggesting that moving to autogenerated docs implies
destroying pages like "List Reorderer API" and their kin? Those
were an awful lot of work to produce that indeed it would be silly
to stuff into a single .js file :P

Boz, rather short of oxygen...

Quoting Anastasia Cheetham <a.cheetham at utoronto.ca>:

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



----------------------------------------------------------------
This message was sent using IMP, the Internet Messaging Program.