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.
Unified · Split
| @@ -64,6 +64,8 @@ Example kernel-doc function comment: · 63 unmodified lines | ||
| 64 | 64 | * comment lines. |
| 65 | 65 | * |
| 66 | 66 | * The longer description can have multiple paragraphs. |
| 67 | + * | |
| 68 | + * Return: Describe the return value of foobar. | |
| 67 | 69 | */ |
| 68 | 70 | |
| 69 | 71 | 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 · 8 unmodified lines | ||
| 78 | 80 | kernel-doc notation as: |
| 79 | 81 | * @...: description |
| 80 | 82 | |
| 83 | +The return value, if any, should be described in a dedicated section | |
| 84 | +named "Return". | |
| 81 | 85 | |
| 82 | 86 | Example kernel-doc data structure comment. |
| 83 | 87 | |
| @@ -222,6 +226,9 @@ only a "*"). · 138 unmodified lines | ||
| 222 | 226 | "section header:" names must be unique per function (or struct, |
| 223 | 227 | union, typedef, enum). |
| 224 | 228 | |
| 229 | +Use the section header "Return" for sections describing the return value | |
| 230 | +of a function. | |
| 231 | + | |
| 225 | 232 | Avoid putting a spurious blank line after the function name, or else the |
| 226 | 233 | description will be repeated! |
| 227 | 234 | |
| @@ -237,21 +244,21 @@ patterns, which are highlighted appropriately. · 9 unmodified lines | ||
| 237 | 244 | NOTE 1: The multi-line descriptive text you provide does *not* recognize |
| 238 | 245 | line breaks, so if you try to format some text nicely, as in: |
| 239 | 246 | |
| 240 | − Return codes | |
| 247 | + Return: | |
| 241 | 248 | 0 - cool |
| 242 | 249 | 1 - invalid arg |
| 243 | 250 | 2 - out of memory |
| 244 | 251 | |
| 245 | 252 | this will all run together and produce: |
| 246 | 253 | |
| 247 | − Return codes 0 - cool 1 - invalid arg 2 - out of memory | |
| 254 | + Return: 0 - cool 1 - invalid arg 2 - out of memory | |
| 248 | 255 | |
| 249 | 256 | NOTE 2: If the descriptive text you provide has lines that begin with |
| 250 | 257 | some phrase followed by a colon, each of those phrases will be taken as |
| 251 | 258 | a new section heading, which means you should similarly try to avoid text |
| 252 | 259 | like: |
| 253 | 260 | |
| 254 | − Return codes: | |
| 261 | + Return: | |
| 255 | 262 | 0: cool |
| 256 | 263 | 1: invalid arg |
| 257 | 264 | 2: out of memory |