I would like to see some coverage of documentation standards in the coding guidelines. I would be nice if we started requiring functions and their parameters to be documented using something like the kernel-doc format:
/**
* foobar() - short function description of foobar
* @arg1: Describe the first argument to foobar.
* @arg2: Describe the second argument to foobar.
* One can provide multiple line descriptions
* for arguments.
*
* A longer description, with more discussion of the function foobar()
* that might be useful to those using or modifying it. Begins with
* empty comment line, and may include additional embedded empty
* comment lines.
*
* The longer description can have multiple paragraphs.
*/
This would be very helpful for new Lustre developers.
3 Comments
Liang Zhen
great, we definitely need this because we have new engineers, :-)
Ned Bass
I would like to see some coverage of documentation standards in the coding guidelines. I would be nice if we started requiring functions and their parameters to be documented using something like the kernel-doc format:
This would be very helpful for new Lustre developers.
Andreas Dilger
Lustre uses DOxygen comment format, but otherwise I agree.