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

[Jakub Kicinski]

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.