[OpenAFS-devel] AFS cache manager documentation

[Simon Wilkinson]

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.

> It's not really clear for me how these "changes" will get merged.

Essentially, you produce a patch, put it in rt (rt.central.org/rt),  
and either Derrick, Jeff or Russ will commit it. Of course, it's a  
good idea before doing the work to make sure that they're happy about  
committing those kinds of changes - but I guess that's the reason for  
your email!

Cheers,

Simon.