Uploaded image for project: 'Lustre'
  1. Lustre
  2. LU-1892

In-tree documentation improvements

    XMLWordPrintable

Details

    • Improvement
    • Resolution: Unresolved
    • Minor
    • None
    • None
    • 10217

    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

      Attachments

        Activity

          People

            pjones Peter Jones
            nedbass Ned Bass (Inactive)
            Votes:
            0 Vote for this issue
            Watchers:
            4 Start watching this issue

            Dates

              Created:
              Updated: