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: <Z2EO45xuUkzlw-Uy@pengutronix.de>
Date: Tue, 17 Dec 2024 06:40:51 +0100
From: Oleksij Rempel <o.rempel@...gutronix.de>
To: Jakub Kicinski <kuba@...nel.org>
Cc: "Russell King (Oracle)" <linux@...linux.org.uk>,
	Paolo Abeni <pabeni@...hat.com>,
	"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 Mon, Dec 16, 2024 at 05:53:16PM -0800, Jakub Kicinski wrote:
> On Mon, 16 Dec 2024 13:20:22 +0100 Oleksij Rempel wrote:
> > On Tue, Dec 10, 2024 at 06:37:04AM -0800, Jakub Kicinski wrote:
> > > > 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 :(  
> > 
> > Please rephrase, I do not understand.
> > 
> > Should I resend this patch with corrected "Return:" description, or
> > continue with inlined comments withing the struct and drop this patch?
> 
> I'm not talking about Returns, I'm talking about the core idea of
> the patch. The duplicate definitions seem odd, can we teach kernel-doc
> to understand function args instead? Most obvious format which comes 
> to mind:
> 
> 	* ...
> 	* @config_init - Initialize the PHY, including after a reset.
> 	* @config_init.phydev: The PHY device to initialize.
> 	*
> 	* Returns: 0 on success or a negative error code on failure.
> 	* ...

It will be too many side quests to me for now. I can streamline comments
if there is agreement how it should look like. But fixing kdoc - I would leave
it to the experts.

What do you prefer, proceed with stats patch without fixing comments or
fix comment without fixing kdoc?

-- 
Pengutronix e.K.                           |                             |
Steuerwalder Str. 21                       | http://www.pengutronix.de/  |
31137 Hildesheim, Germany                  | Phone: +49-5121-206917-0    |
Amtsgericht Hildesheim, HRA 2686           | Fax:   +49-5121-206917-5555 |