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

[Jakub Kicinski <kuba@kernel.org>]

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.
	* ...