What should we do about API documentation?

[Anastasia Cheetham]

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  
code...

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