linux-kernel - Re: [PATCH net-next v1 1/1] net: phy: Move callback comments from struct to kernel-doc section

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: <20241210063704.09c0ac8a@kernel.org>
Date: Tue, 10 Dec 2024 06:37:04 -0800
From: Jakub Kicinski <kuba@...nel.org>
To: "Russell King (Oracle)" <linux@...linux.org.uk>
Cc: Paolo Abeni <pabeni@...hat.com>, Oleksij Rempel
 <o.rempel@...gutronix.de>, "David S. Miller" <davem@...emloft.net>, Eric
 Dumazet <edumazet@...gle.com>, Andrew Lunn <andrew+netdev@...n.ch>, Heiner
 Kallweit <hkallweit1@...il.com>, Jonathan Corbet <corbet@....net>,
 kernel@...gutronix.de, linux-kernel@...r.kernel.org,
 netdev@...r.kernel.org, Simon Horman <horms@...nel.org>, Maxime Chevallier
 <maxime.chevallier@...tlin.com>, linux-doc@...r.kernel.org
Subject: Re: [PATCH net-next v1 1/1] net: phy: Move callback comments from
 struct to kernel-doc section

On Tue, 10 Dec 2024 14:02:09 +0000 Russell King (Oracle) wrote:
> On Tue, Dec 10, 2024 at 12:56:07PM +0100, Paolo Abeni wrote:
> > On 12/6/24 12:39, Oleksij Rempel wrote:  
> > > +#if 0 /* For kernel-doc purposes only. */
> > > +
> > > +/**
> > > + * soft_reset - Issue a PHY software reset.
> > > + * @phydev: The PHY device to reset.
> > > + *
> > > + * Returns 0 on success or a negative error code on failure.  
> > 
> > KDoc is not happy about the lack of ':' after 'Returns':
> > 
> > include/linux/phy.h:1099: warning: No description found for return value
> > of 'soft_reset'  
> 
> We have a huge amount of kernel-doc comments that use "Returns" without
> a colon. I've raised this with Jakub previously, and I think kernel-doc
> folk were quite relaxed about the idea of allowing it if there's enough
> demand.

Ack, and I do apply your patches. IIRC lack of Returns: in a C source 
now causes a W=1 build warning, which I personally think was a wrong
decision, it's a distraction. W=2 would be more appropriate.

> I certainly can't help but write the "returns" statement in natural
> English, rather than kernel-doc "Returns:" style as can be seen from
> my recent patches that have been merged. "Returns" without a colon is
> just way more natural when writing documentation.
> 
> IMHO, kernel-doc has made a wrong decision by requiring the colon.

For the patch under consideration, however, I think _some_ attempt 
to make fully documenting callbacks inline possible needs to be made :(