[LU-1892] In-tree documentation improvements

• Type: Improvement
• Resolution: Unresolved
• Priority: Minor
• Labels: documentation
• Assignee: Peter Jones
• Reporter: Ned Bass (Inactive)

Description

The Lustre code base has a number 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 (See guidelines)
• More thorough high-level description at the top of each 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