Well, API docs are not really a substitute for general docs. But I think a core of automatically-generated API docs have been proved in a wide variety of projects to be appropriate and useful. The total goals of "literate programming" are too wide to go into here, but they include encouraging programmers to be verbal about their intentions, and also would generally tend to be a bit less likely to get out of date, depending on the overall culture :)
To be sure, a good deal of the comments that we have written in the framework code are very close to being written in a Javadoc-type format, and to be honest, I had always assumed that the reason for this was that we either had or were planning to have some kind of automated doc system.... On the duplication point, I think that if this arises, it has to highlight an error in the structure of our documentation. Users shouldn't be taking away a false impression that we have generated separate artefacts such as "List Reorderer", "Grid Reorderer" etc. since this will only impede their understanding and use of the framework :) Whatever reuse structure we have embodied into the framework should also be imputed into the documentation for it.... Cheers, A. Anastasia Cheetham wrote: > > 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 _______________________________________________________ fluid-work mailing list - [email protected] To unsubscribe, change settings or access archives, see http://fluidproject.org/mailman/listinfo/fluid-work
