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