Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit ddf5eabd authored by Yacine Belkadi's avatar Yacine Belkadi Committed by Michal Marek
Browse files

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: default avatarYacine Belkadi <yacine.belkadi.1@gmail.com>
Acked-by: default avatarRandy Dunlap <rdunlap@infradead.org>
Signed-off-by: default avatarMichal Marek <mmarek@suse.cz>
parent ddffeb8c

Documentation/kernel-doc-nano-HOWTO.txt

+10 −3
Original line number Original line Diff line number Diff line
@@ -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