netdev - Re: [PATCH net-next] net: reformat kdoc return statements

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite for Android: free password hash cracker in your pocket

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-ID: <20241118163308.318d8a6b@kernel.org>
Date: Mon, 18 Nov 2024 16:33:08 -0800
From: Jakub Kicinski <kuba@...nel.org>
To: "Russell King (Oracle)" <linux@...linux.org.uk>, Jonathan Corbet
 <corbet@....net>
Cc: davem@...emloft.net, netdev@...r.kernel.org, edumazet@...gle.com,
 pabeni@...hat.com, pablo@...filter.org, richardcochran@...il.com,
 johannes@...solutions.net, loic.poulain@...aro.org, ryazanov.s.a@...il.com,
 dsahern@...nel.org, wintera@...ux.ibm.com, hawk@...nel.org,
 ilias.apalodimas@...aro.org, jhs@...atatu.com, jiri@...nulli.us,
 ecree.xilinx@...il.com, przemyslaw.kitszel@...el.com,
 netfilter-devel@...r.kernel.org, linux-wireless@...r.kernel.org,
 linux-doc@...r.kernel.org
Subject: Re: [PATCH net-next] net: reformat kdoc return statements

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.