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

["Russell King (Oracle)" <linux@armlinux.org.uk>]

On Tue, Dec 17, 2024 at 06:40:51AM +0100, Oleksij Rempel wrote:
> 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.

This is the fundamental problem with kernel-doc, when it's missing
something that really should already be there. It's not like we're
the first to use function pointers in structs - that's a thing that
the kernel has been doing for decades.

I also have no desire to attempt to fix kernel-doc - I know absolutely
nothing about the formatting programs used by kernel-doc (I don't do
any of the "pretty" stuff - when writing stuff for OLS, I had to learn
whatever typesetting system AJH wanted and quickly forgot it
afterwards.) The amount of time that would need to be invested is
beyond what I'm willing to put in - and it would mean shelving
everything else that I'm working on while I did it. That includes me
stopping doing patch reviews while I'm trying to get that sorted.
Given that I've already had Christmas/New Year break from that and
now have a massive backlog. No. Just no. It's just unreasonable to
expect kernel-doc to be fixed in this regard by people who know
nothing about it.

-- 
RMK's Patch system: https://www.armlinux.org.uk/developer/patches/
FTTP is here! 80Mbps down 10Mbps up. Decent connectivity at last!