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!
