diff options
author | Yacine Belkadi <yacine.belkadi.1@gmail.com> | 2012-11-26 22:21:23 +0100 |
---|---|---|
committer | Jiri Kosina <jkosina@suse.cz> | 2012-11-27 21:08:57 +0100 |
commit | e65fe5a91404af97a7a487e6c7606fb5e3807d7d (patch) | |
tree | 5790d6f288fbe922a622d875179caf35799a140b /Documentation | |
parent | 501f9d4c1d5cb524e7c2be1203b5edc4a8edf593 (diff) | |
download | lwn-e65fe5a91404af97a7a487e6c7606fb5e3807d7d.tar.gz lwn-e65fe5a91404af97a7a487e6c7606fb5e3807d7d.zip |
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>
Diffstat (limited to 'Documentation')
-rw-r--r-- | Documentation/kernel-doc-nano-HOWTO.txt | 13 |
1 files changed, 10 insertions, 3 deletions
diff --git a/Documentation/kernel-doc-nano-HOWTO.txt b/Documentation/kernel-doc-nano-HOWTO.txt index 3d8a97747f77..99b57abddf8a 100644 --- a/Documentation/kernel-doc-nano-HOWTO.txt +++ b/Documentation/kernel-doc-nano-HOWTO.txt @@ -64,6 +64,8 @@ Example kernel-doc function comment: * comment lines. * * The longer description can have multiple paragraphs. + * + * Return: Describe the return value of foobar. */ 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: * @...: description +The return value, if any, should be described in a dedicated section +named "Return". Example kernel-doc data structure comment. @@ -222,6 +226,9 @@ only a "*"). "section header:" names must be unique per function (or struct, 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 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 line breaks, so if you try to format some text nicely, as in: - Return codes + Return: 0 - cool 1 - invalid arg 2 - out of memory 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 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 like: - Return codes: + Return: 0: cool 1: invalid arg 2: out of memory |