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: <20241216175316.6df45645@kernel.org>
Date: Mon, 16 Dec 2024 17:53:16 -0800
From: Jakub Kicinski <kuba@...nel.org>
To: Oleksij Rempel <o.rempel@...gutronix.de>
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, 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.
	* ...