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

Message ID 20210127112554.3770172-6-lee.jones@linaro.org
State New
Headers show
Series
  • [01/12] thunderbolt: dma_port: Remove unused variable 'ret'
Related show

Commit Message

Lee Jones Jan. 27, 2021, 11:25 a.m.
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'

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(-)

-- 
2.25.1

Comments

Lee Jones Jan. 27, 2021, 4:13 p.m. | #1
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
Mika Westerberg Jan. 27, 2021, 5 p.m. | #2
On Wed, Jan 27, 2021 at 04:13:20PM +0000, Lee Jones wrote:
> 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.


Thanks for pointing these out. I prefer we fix the kernel-docs (add what
is missing) instead. I'll take care of that.
Lee Jones Jan. 28, 2021, 8:23 a.m. | #3
On Wed, 27 Jan 2021, Mika Westerberg wrote:

> On Wed, Jan 27, 2021 at 04:13:20PM +0000, Lee Jones wrote:

> > 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.

> 

> Thanks for pointing these out. I prefer we fix the kernel-docs (add what

> is missing) instead. I'll take care of that.


Are you planning on actually using this?

I don't see a Doc link for these functions in Mainline:

  `git grep kernel-doc:: | grep thunderbolt`
  
-- 
Lee Jones [李琼斯]
Senior Technical Lead - Developer Services
Linaro.org │ Open source software for Arm SoCs
Follow Linaro: Facebook | Twitter | Blog
Mika Westerberg Jan. 28, 2021, 8:27 a.m. | #4
On Thu, Jan 28, 2021 at 08:23:30AM +0000, Lee Jones wrote:
> On Wed, 27 Jan 2021, Mika Westerberg wrote:

> 

> > On Wed, Jan 27, 2021 at 04:13:20PM +0000, Lee Jones wrote:

> > > 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.

> > 

> > Thanks for pointing these out. I prefer we fix the kernel-docs (add what

> > is missing) instead. I'll take care of that.

> 

> Are you planning on actually using this?


Yes, eventually :)

> I don't see a Doc link for these functions in Mainline:

> 

>   `git grep kernel-doc:: | grep thunderbolt`


There is not one now but I would like to have the kernel-docs at least
in correct format so we can add the link later.
Lee Jones Jan. 28, 2021, 8:38 a.m. | #5
On Thu, 28 Jan 2021, Mika Westerberg wrote:

> On Thu, Jan 28, 2021 at 08:23:30AM +0000, Lee Jones wrote:

> > On Wed, 27 Jan 2021, Mika Westerberg wrote:

> > 

> > > On Wed, Jan 27, 2021 at 04:13:20PM +0000, Lee Jones wrote:

> > > > 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.

> > > 

> > > Thanks for pointing these out. I prefer we fix the kernel-docs (add what

> > > is missing) instead. I'll take care of that.

> > 

> > Are you planning on actually using this?

> 

> Yes, eventually :)


:)

> > I don't see a Doc link for these functions in Mainline:

> > 

> >   `git grep kernel-doc:: | grep thunderbolt`

> 

> There is not one now but I would like to have the kernel-docs at least

> in correct format so we can add the link later.


Very well.

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

Patch

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. The
@@ -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.