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