Jakub Kicinski <kuba@xxxxxxxxxx> writes: > On Sat, 16 Nov 2024 16:23:59 +0000 Russell King (Oracle) wrote: >> On Fri, Nov 15, 2024 at 08:36:12AM -0800, Jakub Kicinski wrote: >> > kernel-doc -Wall warns about missing Return: statement for non-void >> > functions. We have a number of kdocs in our headers which are missing >> > the colon, IOW they use >> > * Return some value >> > or >> > * Returns some value >> > >> > Having the colon makes some sense, it should help kdoc parser avoid >> > false positives. So add them. This is mostly done with a sed script, >> > and removing the unnecessary cases (mostly the comments which aren't >> > kdoc). >> >> I wonder about this... I suspect it's going to be a constant battle to >> ensure that docs use Return: or Returns: because it's not "natural" >> when writing documentation. >> >> Maybe the tooling should accept a sentence starting "Return(s?)" and >> convert it to "Return(s):" in generated documentation? > > I missed this merge window, so we have time, let's ask Jon. > > Jon, do you have a preference on making the kernel-doc formatting > accept "* Return" without the colon? vs fixing all the mis-formatting? > Looks like we have roughly 100 of those in networking headers > (just counting those under include/). I guess my preference would be to fix the comments and keep the tighter rule for the format. It's not something I feel hugely strongly about, though, so I don't think I would try to block an attempt to go the other way. Thanks, jon
