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