On Thu, 28 Jan 2021, Mika Westerberg wrote:

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

quoted

On Wed, 27 Jan 2021, Mika Westerberg wrote:

quoted

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

quoted

On Wed, 27 Jan 2021, Andy Shevchenko wrote:

quoted

On Wednesday, January 27, 2021, Lee Jones [off-list ref] wrote:

quoted

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

:)

quoted

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