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

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.

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