lkml.org 
[lkml]   [2021]   [Feb]   [7]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
/
Date
From
SubjectRe: [PATCH 1/2] Add namespace tags that can be used for matching without pinning a ns
On Fri, Feb 05, 2021 at 08:25:35AM +0000, David Howells wrote:
> Jarkko Sakkinen <jarkko@kernel.org> wrote:
>
> > > + * init_ns_common - Initialise the common part of a namespace
> >
> > Nit: init_ns_common()
>
> Interesting. The majority of code doesn't put the brackets in.
>
> > I've used lately (e.g. arch/x86/kernel/cpu/sgx/ioctl.c) along the lines:
> >
> > * Return:
> > * - 0: Initialization was successful.
> > * - -ENOMEM: Out of memory.
>
> Actually, looking at kernel-doc.rst, this isn't necessarily the recommended
> approach as it will much everything into one line, complete with dashes, and
> can't handle splitting over lines. You probably meant:
>
> * Return:
> * * 0 - OK to runtime suspend the device
> * * -EBUSY - Device should not be runtime suspended

A line beginning with dash, lines up just as well, as one beginning with
an asterisk. I've also tested this with "make htmldocs".

This is Mauro's response to my recent patch:

https://lore.kernel.org/lkml/20210125105353.5c695d42@coco.lan/

So, what I can make up from this is that they are equally good
alternatives.

What I'm not still fully registering is the dash after the return value.

I mean double comma is used after parameter. Why this weird dash syntax
is used after return value I have no idea, and the kernel-doc.rst does
not provide any explanation.

>
> > * Return:
> > * - 0: Initialization was successful.
> > * - -ENOMEM: Out of memory.
> >
> > Looking at the implementation, I guess this is a complete representation of
> > what it can return?
>
> It isn't. It can return at least -ENOSPC as well, but it's awkward detailing
> the errors from functions it calls since they can change and then the
> description here is wrong. I'm not sure there's a perfect answer to that.
>
> David

What if you just add this as the last entry:

* * -errno: Otherwise.

/Jarkko

\
 
 \ /
  Last update: 2021-02-08 00:58    [W:0.059 / U:0.552 seconds]
©2003-2020 Jasper Spaans|hosted at Digital Ocean and TransIP|Read the blog|Advertise on this site