Kernel-doc: Convention: Use a "Return" section to describe return values
Non-void functions should describe their return values in their kernel-doc comments. Currently, some don't, others do in various forms. For example: * Return the result. * Return: The result. * Returns the result. * Returns: the result. * Return Value: The result. * @return: the result. * This function returns the result. * It will return the result. Defining a convention would improve consistency of kernel-doc comments. It would also help scripts/kernel-doc identify the text describing the return value of a function. Thus allowing additional checks on the comments, and suitable highlighting in the generated docs (man pages, html, etc). So, as a convention, use a section named "Return" to describe the return value of a function. Signed-off-by: Yacine Belkadi <yacine.belkadi.1@gmail.com> Signed-off-by: Rob Landley <rob@landley.net> Signed-off-by: Jiri Kosina <jkosina@suse.cz>
This commit is contained in:
parent
501f9d4c1d
commit
e65fe5a914
|
@ -64,6 +64,8 @@ Example kernel-doc function comment:
|
||||||
* comment lines.
|
* comment lines.
|
||||||
*
|
*
|
||||||
* The longer description can have multiple paragraphs.
|
* The longer description can have multiple paragraphs.
|
||||||
|
*
|
||||||
|
* Return: Describe the return value of foobar.
|
||||||
*/
|
*/
|
||||||
|
|
||||||
The short description following the subject can span multiple lines
|
The short description following the subject can span multiple lines
|
||||||
|
@ -78,6 +80,8 @@ If a function parameter is "..." (varargs), it should be listed in
|
||||||
kernel-doc notation as:
|
kernel-doc notation as:
|
||||||
* @...: description
|
* @...: description
|
||||||
|
|
||||||
|
The return value, if any, should be described in a dedicated section
|
||||||
|
named "Return".
|
||||||
|
|
||||||
Example kernel-doc data structure comment.
|
Example kernel-doc data structure comment.
|
||||||
|
|
||||||
|
@ -222,6 +226,9 @@ only a "*").
|
||||||
"section header:" names must be unique per function (or struct,
|
"section header:" names must be unique per function (or struct,
|
||||||
union, typedef, enum).
|
union, typedef, enum).
|
||||||
|
|
||||||
|
Use the section header "Return" for sections describing the return value
|
||||||
|
of a function.
|
||||||
|
|
||||||
Avoid putting a spurious blank line after the function name, or else the
|
Avoid putting a spurious blank line after the function name, or else the
|
||||||
description will be repeated!
|
description will be repeated!
|
||||||
|
|
||||||
|
@ -237,21 +244,21 @@ patterns, which are highlighted appropriately.
|
||||||
NOTE 1: The multi-line descriptive text you provide does *not* recognize
|
NOTE 1: The multi-line descriptive text you provide does *not* recognize
|
||||||
line breaks, so if you try to format some text nicely, as in:
|
line breaks, so if you try to format some text nicely, as in:
|
||||||
|
|
||||||
Return codes
|
Return:
|
||||||
0 - cool
|
0 - cool
|
||||||
1 - invalid arg
|
1 - invalid arg
|
||||||
2 - out of memory
|
2 - out of memory
|
||||||
|
|
||||||
this will all run together and produce:
|
this will all run together and produce:
|
||||||
|
|
||||||
Return codes 0 - cool 1 - invalid arg 2 - out of memory
|
Return: 0 - cool 1 - invalid arg 2 - out of memory
|
||||||
|
|
||||||
NOTE 2: If the descriptive text you provide has lines that begin with
|
NOTE 2: If the descriptive text you provide has lines that begin with
|
||||||
some phrase followed by a colon, each of those phrases will be taken as
|
some phrase followed by a colon, each of those phrases will be taken as
|
||||||
a new section heading, which means you should similarly try to avoid text
|
a new section heading, which means you should similarly try to avoid text
|
||||||
like:
|
like:
|
||||||
|
|
||||||
Return codes:
|
Return:
|
||||||
0: cool
|
0: cool
|
||||||
1: invalid arg
|
1: invalid arg
|
||||||
2: out of memory
|
2: out of memory
|
||||||
|
|
Reference in New Issue