On Tue, Apr 22, 2008 at 12:18 PM, Simon Wilkinson <[EMAIL PROTECTED]> 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 [EMAIL PROTECTED] for some Emacs macros that he has put together to help do the first pass changes. Steven _______________________________________________ OpenAFS-devel mailing list [email protected] https://lists.openafs.org/mailman/listinfo/openafs-devel
