On Tue, Dec 17, 2024 at 06:40:51AM +0100, Oleksij Rempel wrote: > 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. This is the fundamental problem with kernel-doc, when it's missing something that really should already be there. It's not like we're the first to use function pointers in structs - that's a thing that the kernel has been doing for decades. I also have no desire to attempt to fix kernel-doc - I know absolutely nothing about the formatting programs used by kernel-doc (I don't do any of the "pretty" stuff - when writing stuff for OLS, I had to learn whatever typesetting system AJH wanted and quickly forgot it afterwards.) The amount of time that would need to be invested is beyond what I'm willing to put in - and it would mean shelving everything else that I'm working on while I did it. That includes me stopping doing patch reviews while I'm trying to get that sorted. Given that I've already had Christmas/New Year break from that and now have a massive backlog. No. Just no. It's just unreasonable to expect kernel-doc to be fixed in this regard by people who know nothing about it. -- RMK's Patch system: https://www.armlinux.org.uk/developer/patches/ FTTP is here! 80Mbps down 10Mbps up. Decent connectivity at last!
