[LU-1892] In-tree documentation improvements

• Type: Improvement
• Resolution: Done
• 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

Issue Links

• is related to: LU-9633 Add kernel-doc style comments to All lustre Code describing function & parameters.

Comments

[Andreas Dilger]

While I can't say that all of the in-tree documentation has been fixed, there are newer tickets used for this (e.g. LU-9633) and this one isn't tracking anything useful.

[Gerrit Updater]

Oleg Drokin ([e-mail]) merged in patch http://review.whamcloud.com/12659/
Subject: LU-1892 osp: Fix Doxygen warnings for osp_trans.c
Project: fs/lustre-release
Branch: master
Current Patch Set:
Commit: 99a05bdd378be62c31e0e2320310871eb9c9b68b

[Ned Bass (Inactive)]

After reviewing many of the patches in the sub-task issues, I think we could standardize and improve how we use the doxygen command \retval. The format should be as follows (see manual)

\retval <return value> { description }

Where the first two fields are separated by a single space, <return value> is a single word (positive, negative, pointer, size, etc.), and the description is tab-indented. For example,

 * \retval 0                 FID lookup succeeded
 * \retval negative          negated errno if lookup failed

This convention would improve code readability and the quality of automatically generated documentation.

[Cory Spitz]

FYI: Hugo F. took an action item from the CDWG LUG meeting to work out whether we can start building on the LID (http://wiki.lustre.org/lid) as part of the lustre.org asset assignment to OpenSFS and EOFS.

[Ned Bass (Inactive)]

Here are the open tickets I found and their status.

bz	summary	patch status	Assignee/Author
20943	Doxygen comments - ldlm module	inspection+/not landed	Oleg
20969	Doxygen comments - ptlrpc module	landed	Oleg
20973	Doxygen comments - lnet module	landed	Isaac Huang
20974	Doxygen comments - libcfs module	inspection+/not landed	Maxim Patlasov
20976	Doxygen comments - liblustre module	nonexistent	Oleg
21833	Doxygen comments - lustre target code	inspection-/not landed	Mikhail
23011	Doxygen comments - OSD module	nonexistent	Mikhail
23718	Doxygen style comments on gss/kerberos code	landed	Eric Mei

[Ned Bass (Inactive)]

Good idea, I'll search for them and start evaluating.

[Andreas Dilger]

Ned, I was poking around Bugzilla last week, and in fact there appear to be a number of bugs with patches for DOxygen comments in them that are still open. It would probably make a lot of sense to take a look at those patches, and either determine they have already landed and close the bugs, or update the patches for master under this patch (and still close those bugs).