[OpenAFS-devel] AFS cache manager documentation

[Steven Jenkins]

On Tue, Apr 22, 2008 at 12:18 PM, Simon Wilkinson <sxw@inf.ed.ac.uk> wrote:
>
>  On 22 Apr 2008, at 16:54, Dragos Tatulea wrote:
>
> >    During the Google Summer of Code "community bonding period" the
> students have to become aquainted with the OpenAFS internals. In order to
> make the best of this month, I would like to document all the gained info on
> the Cache Manager. There are multiple ways of doing this. Jeffrey Altman
> mentioned two types of documentation that he would like to see:
> > - per module architectural docs, providing a general description of a
> module (e.g.: VNOPS, dcache, vcache, etc).
> > - per function docs, describing it's use and contents.
> > He suggested doxygen for this.
> >
>
>  Personally, I'd prefer any mechanism that keeps the documentation with the
> code, as it at least creates the chance that people modifiying the code also
> fix the docs. My experience with docs held separately is that they rot
> really quickly.
>
>  doxygen, regardless of its foibles, seems to be the 'preferred' mechanism
> for doing this.
>

We've found doxygen to be usable.  We've found that often there are
comments that are already suitable, but they just need to be
re-formatted slightly for doxygen to pick them up.  You may find it
best to do a first pass to get those into doxygen, and then do a
second pass filling out a more comprehensive set of docs.

You can contact charles@endpoint.com for some Emacs macros that he has
put together to help do the first pass changes.

Steven