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