Re: [PATCH rdma-rc 1/2] RDMA/mlx5: Set correct kernel-doc identifier

[Lee Jones <lee.jones@linaro.org>]

On Tue, 02 Mar 2021, Leon Romanovsky wrote:

> On Tue, Mar 02, 2021 at 09:31:09AM +0000, Lee Jones wrote:
> > On Tue, 02 Mar 2021, Leon Romanovsky wrote:
> >
> > > From: Leon Romanovsky <leonro@nvidia.com>
> > >
> > > The W=1 allmodconfig build produces the following warning:
> > > drivers/infiniband/hw/mlx5/odp.c:1086: warning: wrong kernel-doc identifier on line:
> > >   * Parse a series of data segments for page fault handling.
> > >
> > > Fix it by changing /** to be /* as it is written in kernel-doc documentation.
> > >
> > > Fixes: 5e769e444d26 ("RDMA/hw/mlx5/odp: Fix formatting and add missing descriptions in 'pagefault_data_segments()'")
> > > Signed-off-by: Leon Romanovsky <leonro@nvidia.com>
> > > ---
> > >  drivers/infiniband/hw/mlx5/odp.c | 2 +-
> > >  1 file changed, 1 insertion(+), 1 deletion(-)
> > >
> > > diff --git a/drivers/infiniband/hw/mlx5/odp.c b/drivers/infiniband/hw/mlx5/odp.c
> > > index 374698186662..b103555b1f5d 100644
> > > --- a/drivers/infiniband/hw/mlx5/odp.c
> > > +++ b/drivers/infiniband/hw/mlx5/odp.c
> > > @@ -1082,7 +1082,7 @@ static int pagefault_single_data_segment(struct mlx5_ib_dev *dev,
> > >  	return ret ? ret : npages;
> > >  }
> > >
> > > -/**
> > > +/*
> >
> > This is not the correct fix.
> 
> I don't want kernel-doc comments on static function. It is local to this
> file, so change from /** to /* was to mark that this is not kernel-doc.
> 
> >
> > Kernel-doc is asking for the function name.
> 
> The thing is that I don't want it to be kernel-doc.

In the past, if the authors have made a good effort to document the
function, I have left the kernel-doc formatting in place.  It looks
odd / non-consistent to demote some, but not others.  Especially
considering there are 100's if not 1000's of other static functions
documented in the kernel with kernel-doc formatting.

There are also 1000's of uses that are left referenced by kernel-doc::
tags.  See: scripts/find-unused-docs.sh for more details.

If you're going to go through with this, you should at least say what
you're doing and why in the commit message.  Since demoting an
otherwise full and complete kernel-doc header seems a little harsh to
say the least.

-- 
Lee Jones [李琼斯]
Senior Technical Lead - Developer Services
Linaro.org │ Open source software for Arm SoCs
Follow Linaro: Facebook | Twitter | Blog