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

[Jakub Kicinski <kuba@kernel.org>]

On Tue, 10 Dec 2024 14:02:09 +0000 Russell King (Oracle) wrote:
> On Tue, Dec 10, 2024 at 12:56:07PM +0100, Paolo Abeni wrote:
> > On 12/6/24 12:39, Oleksij Rempel wrote:  
> > > +#if 0 /* For kernel-doc purposes only. */
> > > +
> > > +/**
> > > + * soft_reset - Issue a PHY software reset.
> > > + * @phydev: The PHY device to reset.
> > > + *
> > > + * Returns 0 on success or a negative error code on failure.  
> > 
> > KDoc is not happy about the lack of ':' after 'Returns':
> > 
> > include/linux/phy.h:1099: warning: No description found for return value
> > of 'soft_reset'  
> 
> We have a huge amount of kernel-doc comments that use "Returns" without
> a colon. I've raised this with Jakub previously, and I think kernel-doc
> folk were quite relaxed about the idea of allowing it if there's enough
> demand.

Ack, and I do apply your patches. IIRC lack of Returns: in a C source 
now causes a W=1 build warning, which I personally think was a wrong
decision, it's a distraction. W=2 would be more appropriate.

> 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 :(