[LUDOC-77] In-tree documentation improvements

Tue, 29 Apr 2014 20:04:45 +0000

The Lustre code base has a number of undocumented areas, making it difficult for new developers to get their bearings. This issue is to track patches that add comments and documentation to the Lustre source tree, and to discuss how to approach the problem of documenting the code better. In particular, I have in mind the following types of improvements.

Doxygen comment headers on all non-trivial functions
More thorough high-level description at the top of each source file stating its reason for existing
Description of how the code is organized, i.e. what each directory is for
High level overview of Lustre internal architecture
Deep-dives into specific subsystems (i.e. http://wiki.lustre.org/images/3/37/CLIO-TOI-notes.pdf for CLIO)

While one could argue that the architectural content belongs in an external developers manual, developing it in-tree has several benefits.

It is easier for someone poking around in the code to quickly come up to speed
Code changes can include corresponding documentation updates in the same patch
Plain text documentation can be evolved rapidly and informally and later incorporated into a formal manual
It is consistent with how the Documentation directory is used in the Linux kernel

Whamcloud Community JIRA

[LUDOC-77] In-tree documentation improvements