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 [email protected]
Software Designer, Fluid Project http://fluidproject.org
Adaptive Technology Resource Centre / University of Toronto
_______________________________________________________
fluid-work mailing list - [email protected]
To unsubscribe, change settings or access archives,
see http://fluidproject.org/mailman/listinfo/fluid-work
