lkml.org 
[lkml]   [2021]   [Jan]   [26]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
/
Date
From
SubjectRe: [PATCH] kernel-doc: Make the description of return value readable
Em Mon, 25 Jan 2021 10:19:04 +0200
Jarkko Sakkinen <jarkko@kernel.org> escreveu:

> The description on how to describe return values is over-complicated, and
> hard to follow. For alien reason, the body of the section is a note, and
> the first paragraph speaks about 'Return', albeit the section name is
> actually 'Return:'.
>
> To give a better help when both implementing and reviewing patches, provide
> a straight-forward guideline, how to decribe return values, instead of
> providing a note that starts by "blacklisting" one of the infinite possible
> options of doing it wrong.
>
> This decreases the cumulative amount of time, which is probably
> substantial, on this otherwise somewhat trivial topic.
>
> Signed-off-by: Jarkko Sakkinen <jarkko@kernel.org>
> ---
> Documentation/doc-guide/kernel-doc.rst | 34 +++++++-------------------
> 1 file changed, 9 insertions(+), 25 deletions(-)
>
> diff --git a/Documentation/doc-guide/kernel-doc.rst b/Documentation/doc-guide/kernel-doc.rst
> index 79aaa55d6bcf..dc5e1722c150 100644
> --- a/Documentation/doc-guide/kernel-doc.rst
> +++ b/Documentation/doc-guide/kernel-doc.rst
> @@ -136,34 +136,18 @@ Examples::
> Return values
> ~~~~~~~~~~~~~
>
> -The return value, if any, should be described in a dedicated section
> -named ``Return``.
> +The return value, if any, should be described in a dedicated section named
> +``Return:``.
>
> -.. note::
> -
> - #) The multi-line descriptive text you provide does *not* recognize
> - line breaks, so if you try to format some text nicely, as in::
> -
> - * Return:
> - * 0 - OK
> - * -EINVAL - invalid argument
> - * -ENOMEM - out of memory
> -
> - this will all run together and produce::
> -
> - Return: 0 - OK -EINVAL - invalid argument -ENOMEM - out of memory
> -
> - So, in order to produce the desired line breaks, you need to use a
> - ReST list, e. g.::
> +In order to describe multiple return values, a ReST list should be used. That
> +way Sphinx knows how to line-up them properly::
>
> - * Return:
> - * * 0 - OK to runtime suspend the device
> - * * -EBUSY - Device should not be runtime suspended
> + * Return:
> + * - 0: The run-time is allowed to suspend the device.
> + * - -EBUSY: Device should not be suspended.
>
> - #) 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 probably won't produce the desired
> - effect.
> +Using a dash rather than asterisk an is probably a better idea, because it does
> +not meddle as much with the C-comments.

Well, there are different opinions with that regards... Some devs think that
using:

- -EBUSY

is confusing. I ended agreeing with that. That's why the recommendation is
to use an asterisk.

Thanks,
Mauro

\
 
 \ /
  Last update: 2021-01-26 06:36    [W:0.051 / U:0.152 seconds]
©2003-2020 Jasper Spaans|hosted at Digital Ocean and TransIP|Read the blog|Advertise on this site