Kernel-doc: Convention: Use a "Return" section to describe return values

Browse source

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>
Acked-by: Randy Dunlap <rdunlap@infradead.org>
Signed-off-by: Michal Marek <mmarek@suse.cz>

...

This commit is contained in:

Yacine Belkadi 2012-11-27 21:27:18 +01:00 • committed by Michal Marek

parent ddffeb8c4d

commit ddf5eabd20

1 changed files with 10 additions and 3 deletions

Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL

Download patch file Download diff file Expand all files Collapse all files

13

Documentation/kernel-doc-nano-HOWTO.txt

View file