[OpenAFS-devel] code and API documentation

[Ted Anderson]

On Mon, 27 Jan 2003, Derrick J Brashear wrote:
 > On Mon, 27 Jan 2003, Matthew A. Bacchi wrote:
 > > Is there currently any documentation for the OpenAFS codebase, or
 > > possibly any interest in developing this?  The source tree is
 > > daunting
 >
 > You mean code reference as opposed to API reference? The former,
 > no. The latter, out of date.

This is the point.  I think having an in-source standard for documenting
code and its interfaces is a good thing.  The biggest advantage of using
source comments is that there is a much better chance that the
documentation will be updated and kept in sync with the actual code.

 > > 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.
 >
 > Perhaps there's some other option such that the code doesn't get all
 > smeared up with the documentation?

Since Doxygen supports JavaDoc format[1], basic documentation can be
provided with only a single extra "*".  For example, from cmd.c:

     /* Call the appropriate function, or return syntax error code. 
Note: if no opcode is specified, an initialization routine exists, and 
it has NOT been called before, we invoke the special initialization opcode*/
     int cmd_Dispatch(argc, argv)

could be improved to:

     /** Call the appropriate function, or return syntax error code.
      * Note: if no opcode is specified, an initialization routine
      * exists, and it has NOT been called before, we invoke the special
      * initialization opcode. */
     int cmd_Dispatch(argc, argv)

Okay, so I added line breaks too.

I think there is a useful feedback system that is possible to utilize.
If developers see the benefits of good comments in form of useful
documentation, they will be more likely to add and improve those
comments.

My two cents,
Ted Anderson

[1] http://www.stack.nl/~dimitri/doxygen/docblocks.html