lkml.org 
[lkml]   [2021]   [Jan]   [27]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
/
Date
From
SubjectRe: [PATCH 05/12] thunderbolt: pa: Demote non-conformant kernel-doc headers
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.

\
 
 \ /
  Last update: 2021-01-27 18:06    [W:0.099 / U:0.136 seconds]
©2003-2020 Jasper Spaans|hosted at Digital Ocean and TransIP|Read the blog|Advertise on this site