Re: [PATCH 05/12] thunderbolt: pa: Demote non-conformant kernel-doc headers

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

On Wed, 27 Jan 2021, Andy Shevchenko wrote:

> On Wednesday, January 27, 2021, Lee Jones <lee.jones@linaro.org> wrote:
> 
> > Fixes the following W=1 kernel build warning(s):
> >
> >  drivers/thunderbolt/path.c:476: warning: Function parameter or member
> > 'path' not described in 'tb_path_activate'
> >  drivers/thunderbolt/path.c:568: warning: Function parameter or member
> > 'path' not described in 'tb_path_is_invalid'
> >
> >
> I think the intention was to describe them in kernel doc format, perhaps
> you need to add descriptions of the fields?

For changes like this, I've been working to the following rule:

 - I'll provide fix-ups; if and only if the author has had a
 reasonable attempt at providing a conformant kernel-doc header.

So if the headers are just suffering from a little doc-rot i.e. the
API has changed, but the doc update was omitted, or most of the
parameters/members are documented, but some were forgotten about etc,
or if there are formatting issues, I'll happily take up the slack and
polish those up a bit.

However, if no attempt was made, then they get demoted.

I don't want to get into a situation where authors delicately provide
weak documentation with the expectation that someone else will come
along and turn them into conformant docs.

If authors wish to come back, provide proper descriptions &
formatting and subsequently re-promote them again, then all power to
them.

> > Cc: Andreas Noever <andreas.noever@gmail.com>
> > Cc: Michael Jamet <michael.jamet@intel.com>
> > Cc: Mika Westerberg <mika.westerberg@linux.intel.com>
> > Cc: Yehezkel Bernat <YehezkelShB@gmail.com>
> > Cc: linux-usb@vger.kernel.org
> > Signed-off-by: Lee Jones <lee.jones@linaro.org>
> > ---
> >  drivers/thunderbolt/path.c | 4 ++--
> >  1 file changed, 2 insertions(+), 2 deletions(-)
> >
> > diff --git a/drivers/thunderbolt/path.c b/drivers/thunderbolt/path.c
> > index ca7d738d66dea..758b5fa0060c6 100644
> > --- a/drivers/thunderbolt/path.c
> > +++ b/drivers/thunderbolt/path.c
> > @@ -464,7 +464,7 @@ void tb_path_deactivate(struct tb_path *path)
> >         path->activated = false;
> >  }
> >
> > -/**
> > +/*
> >   * tb_path_activate() - activate a path
> >   *
> >   * Activate a path starting with the last hop and iterating backwards. Thee
> > @@ -559,7 +559,7 @@ int tb_path_activate(struct tb_path *path)
> >         return res;
> >  }
> >
> > -/**
> > +/*
> >   * tb_path_is_invalid() - check whether any ports on the path are invalid
> >   *
> >   * Return: Returns true if the path is invalid, false otherwise.
> >
> >
> 

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