[LU-1892] In-tree documentation improvements Created: 11/Sep/12 Updated: 07/Jun/16 |
|
| Status: | Open |
| Project: | Lustre |
| Component/s: | None |
| Affects Version/s: | None |
| Fix Version/s: | None |
| Type: | Improvement | Priority: | Minor |
| Reporter: | Ned Bass | Assignee: | Peter Jones |
| Resolution: | Unresolved | Votes: | 0 |
| Labels: | documentation | ||
| Sub-Tasks: |
|
||||||||||||||||||||||||||||||||||||||||
| Rank (Obsolete): | 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.
While one could argue that the architectural content belongs in an external developers manual, developing it in-tree has several benefits
|
| Comments |
| Comment by Andreas Dilger [ 11/Sep/12 ] | ||||||||||||||||||||||||||||||||||||
|
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). | ||||||||||||||||||||||||||||||||||||
| Comment by Ned Bass [ 11/Sep/12 ] | ||||||||||||||||||||||||||||||||||||
|
Good idea, I'll search for them and start evaluating. | ||||||||||||||||||||||||||||||||||||
| Comment by Ned Bass [ 11/Sep/12 ] | ||||||||||||||||||||||||||||||||||||
|
Here are the open tickets I found and their status.
| ||||||||||||||||||||||||||||||||||||
| Comment by Cory Spitz [ 29/Apr/14 ] | ||||||||||||||||||||||||||||||||||||
|
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. | ||||||||||||||||||||||||||||||||||||
| Comment by Ned Bass [ 23/Jul/14 ] | ||||||||||||||||||||||||||||||||||||
|
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. | ||||||||||||||||||||||||||||||||||||
| Comment by Gerrit Updater [ 04/Dec/14 ] | ||||||||||||||||||||||||||||||||||||
|
Oleg Drokin (oleg.drokin@intel.com) merged in patch http://review.whamcloud.com/12659/ |