What should we do about API documentation?
a.cheetham at utoronto.ca
Wed Jan 21 18:59:47 UTC 2009
Suggestions for our documentation have included several packages that
automatically generate API documents based on comments in code.
My current feeling is that this approach might be inappropriate for
Infusion. Our docs seem to have a lot more information in them than I
would want to see in comments in the code, for one (for example, the
descriptions of the various options that can be set). Also, there is a
fair bit of duplication of information because of re-use of code (for
example, most of the general Reorderer options are shared by List
Reorderer, Grid Reorderer, etc.).
We also have a lot of documentation that isn't directly API
documentation, and hence couldn't be generated from source files.
So my thinking on this is that a system for generating docs from
comments in the code is not appropriate for us.
However, it's possible that the 'symptoms' could be interpreted
differently - perhaps we *should* be able to produce docs from our
What do other people think about this?
Anastasia Cheetham a.cheetham at utoronto.ca
Software Designer, Fluid Project http://fluidproject.org
Adaptive Technology Resource Centre / University of Toronto
More information about the fluid-work