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/). FWIW we catch new instances of the missing return problem, so it shouldn't be getting worse.
