linux-kernel - Re: [net-next PATCH v3 3/3] net: phy: add support for PHY package MMD read/write

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: <ZW89errbJWUt33vz@shell.armlinux.org.uk>
Date:   Tue, 5 Dec 2023 15:10:50 +0000
From:   "Russell King (Oracle)" <linux@...linux.org.uk>
To:     Andrew Lunn <andrew@...n.ch>
Cc:     Christian Marangi <ansuelsmth@...il.com>,
        Jakub Kicinski <kuba@...nel.org>,
        Florian Fainelli <florian.fainelli@...adcom.com>,
        Broadcom internal kernel review list 
        <bcm-kernel-feedback-list@...adcom.com>,
        Heiner Kallweit <hkallweit1@...il.com>,
        "David S. Miller" <davem@...emloft.net>,
        Eric Dumazet <edumazet@...gle.com>,
        Paolo Abeni <pabeni@...hat.com>,
        David Epping <david.epping@...singlinkelectronics.com>,
        Vladimir Oltean <olteanv@...il.com>,
        Harini Katakam <harini.katakam@....com>,
        netdev@...r.kernel.org, linux-kernel@...r.kernel.org
Subject: Re: [net-next PATCH v3 3/3] net: phy: add support for PHY package
 MMD read/write

On Tue, Dec 05, 2023 at 03:54:04PM +0100, Andrew Lunn wrote:
> > > I tend to agree. These functions should be documented once in kdoc,
> > > and only once. I don't really care if its in the header, or the C
> > > code, but not both.
> > >
> > 
> > Ok just to make sure, I should keep the kdoc in the .c and drop them in
> > .h ? (or should I move the more complete kdoc in .c to .h and remove
> > kdoc in .c?)
> 
> Please put the kdoc in the header file and remove if from the .c file.

phy-core.c follows the style that the kdoc is in the .c file rather
than the header file.

I've raised this before in other subsystems, and it's suggested that
it's better to have it in the .c file. I guess the reason is that it's
more obvious that the function is documented when modifying it, so
there's a higher probability that the kdoc will get updated when the
function is altered.

I guess a question to ask is how often do people modify a function and
then check the header for any documentation?

-- 
RMK's Patch system: https://www.armlinux.org.uk/developer/patches/
FTTP is here! 80Mbps down 10Mbps up. Decent connectivity at last!