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] [day] [month] [year] [list]

Message-ID: <20241217070311.1c867d32@kernel.org>
Date: Tue, 17 Dec 2024 07:03:11 -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 Tue, 17 Dec 2024 06:40:51 +0100 Oleksij Rempel wrote:
> > > 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?

The former. And you're using the word "fix" very loosely here, IMHO.