On Mon, Dec 16, 2024 at 05:53:16PM -0800, Jakub Kicinski wrote: > On Mon, 16 Dec 2024 13:20:22 +0100 Oleksij Rempel wrote: > > On Tue, Dec 10, 2024 at 06:37:04AM -0800, Jakub Kicinski wrote: > > > > 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 :( > > > > 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? -- Pengutronix e.K. | | Steuerwalder Str. 21 | http://www.pengutronix.de/ | 31137 Hildesheim, Germany | Phone: +49-5121-206917-0 | Amtsgericht Hildesheim, HRA 2686 | Fax: +49-5121-206917-5555 |
