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

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [day] [month] [year] [list]

Message-ID: <20210128083847.GD4774@dell>
Date:   Thu, 28 Jan 2021 08:38:47 +0000
From:   Lee Jones <lee.jones@...aro.org>
To:     Mika Westerberg <mika.westerberg@...ux.intel.com>
Cc:     Andy Shevchenko <andy.shevchenko@...il.com>,
        "linux-kernel@...r.kernel.org" <linux-kernel@...r.kernel.org>,
        Andreas Noever <andreas.noever@...il.com>,
        Michael Jamet <michael.jamet@...el.com>,
        Yehezkel Bernat <YehezkelShB@...il.com>,
        "linux-usb@...r.kernel.org" <linux-usb@...r.kernel.org>
Subject: Re: [PATCH 05/12] thunderbolt: pa: Demote non-conformant kernel-doc
 headers

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