linux-kernel - Re: [PATCH 26/30] net: wireless: broadcom: b43: phy_common: Demote non-conformant kerneldoc header

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] [thread-next>] [day] [month] [year] [list]

Message-ID: <20200817091139.GU4354@dell>
Date:   Mon, 17 Aug 2020 10:11:39 +0100
From:   Lee Jones <lee.jones@...aro.org>
To:     Rafał Miłecki <zajec5@...il.com>
Cc:     David Miller <davem@...emloft.net>, kuba@...nel.org,
        Michael Buesch <m@...s.ch>,
        Stefano Brivio <stefano.brivio@...imi.it>,
        Andreas Jaggi <andreas.jaggi@...erwave.ch>,
        Network Development <netdev@...r.kernel.org>,
        "linux-wireless@...r.kernel.org" <linux-wireless@...r.kernel.org>,
        Linux Kernel Mailing List <linux-kernel@...r.kernel.org>,
        b43-dev <b43-dev@...ts.infradead.org>,
        "Alexander A. Klimov" <grandmaster@...klimov.de>,
        Martin Langer <martin-langer@....de>,
        van Dyk <kugelfang@...too.org>,
        Kalle Valo <kvalo@...eaurora.org>
Subject: Re: [PATCH 26/30] net: wireless: broadcom: b43: phy_common: Demote
 non-conformant kerneldoc header

On Mon, 17 Aug 2020, Rafał Miłecki wrote:

> On Fri, 14 Aug 2020 at 13:41, Lee Jones <lee.jones@...aro.org> wrote:
> > Fixes the following W=1 kernel build warning(s):
> >
> >  drivers/net/wireless/broadcom/b43/phy_common.c:467: warning: Function parameter or member 'work' not described in 'b43_phy_txpower_adjust_work'
> 
> Why you can't document @work instead? Should be quite a better solution.

It some circumstances it would, but not this one.

 1. This 'kernel-doc' function is not referenced from any
    documentation location i.e. it is presently unused and there is no
    reason for it to be kernel-doc in the first place.
 2. This patch stops `scripts/find-unused-docs.sh` complaining about
    phy_common.c
 3. 'b43_phy_txpower_adjust_work' is the only function that has been
     documented as kernel-doc - why is that?  Seems like a mistake.
 
-- 
Lee Jones [李琼斯]
Senior Technical Lead - Developer Services
Linaro.org │ Open source software for Arm SoCs
Follow Linaro: Facebook | Twitter | Blog