| Message ID | 20210127112554.3770172-6-lee.jones@linaro.org (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | Rid W=1 warnings from Thunderbolt | expand |
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. > > > > >
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.
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`
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.
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.
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.
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(-)