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: <Z2AbBilPf2JRXNzH@pengutronix.de>
Date: Mon, 16 Dec 2024 13:20:22 +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

Hi Jakub,

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?

Regards,
Oleksij
-- 
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 |