What should we do about API documentation?
antranig at caret.cam.ac.uk
Thu Jan 22 00:05:34 UTC 2009
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....
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
> 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
> fluid-work mailing list - fluid-work at fluidproject.org
> To unsubscribe, change settings or access archives,
> see http://fluidproject.org/mailman/listinfo/fluid-work
More information about the fluid-work