Jakub Kicinski [off-list ref] writes:
On Sat, 16 Nov 2024 16:23:59 +0000 Russell King (Oracle) wrote:
quoted
On Fri, Nov 15, 2024 at 08:36:12AM -0800, Jakub Kicinski wrote:
quoted
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