[OpenAFS-devel] code and API documentation

[Matthew A. Bacchi]

Is there currently any documentation for the OpenAFS codebase, or
possibly any interest in developing this?  The source tree is daunting
to someone who isn't familiar with it.  I have used the AFS
Programmer's Reference from Transarc, but it focuses on the subsystem
specifications only.

I have been using a source documentation tool called doxygen with some
small projects, and think it could be useful here.  I've already run
it against the openafs-1.2.7 release, just to see how it works.  It
basically provides a map of the tree, with cross references of
functions, headers, etc.  But, to make full use of doxygen's
capabilities, commentary would need to be embedded into the source
itself, sorta like JavaDoc, obviously this could be expensive on a
project of this size.

Another downside I see to this, is simply the fact that these comments
take space in the code.  Traditional comments could be replaced
by this commenting style, and obviously would be accessible in HTML
and even PDF or TeX formats with the use of doxygen.  What does
everyone think?  Do you have other ideas, suggestions?

Thanks,
-Matt