lkml.org 
[lkml]   [2021]   [Jan]   [28]   [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 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.

    --
    Lee Jones [李琼斯]
    Senior Technical Lead - Developer Services
    Linaro.org │ Open source software for Arm SoCs
    Follow Linaro: Facebook | Twitter | Blog

    \
     
     \ /
      Last update: 2021-01-28 09:41    [W:3.486 / U:0.052 seconds]
    ©2003-2020 Jasper Spaans|hosted at Digital Ocean and TransIP|Read the blog|Advertise on this site