From: "Russell King (Oracle)" <linux@armlinux.org.uk>
To: Jakub Kicinski <kuba@kernel.org>
Cc: davem@davemloft.net, netdev@vger.kernel.org, edumazet@google.com,
pabeni@redhat.com, pablo@netfilter.org, richardcochran@gmail.com,
johannes@sipsolutions.net, loic.poulain@linaro.org,
ryazanov.s.a@gmail.com, dsahern@kernel.org,
wintera@linux.ibm.com, hawk@kernel.org,
ilias.apalodimas@linaro.org, jhs@mojatatu.com, jiri@resnulli.us,
ecree.xilinx@gmail.com, przemyslaw.kitszel@intel.com,
netfilter-devel@vger.kernel.org, linux-wireless@vger.kernel.org
Subject: Re: [PATCH net-next] net: reformat kdoc return statements
Date: Sat, 16 Nov 2024 16:23:59 +0000 [thread overview]
Message-ID: <ZzjHH-L-ylLe0YhU@shell.armlinux.org.uk> (raw)
In-Reply-To: <20241115163612.904906-1-kuba@kernel.org>
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?
--
RMK's Patch system: https://www.armlinux.org.uk/developer/patches/
FTTP is here! 80Mbps down 10Mbps up. Decent connectivity at last!
next prev parent reply other threads:[~2024-11-16 16:24 UTC|newest]
Thread overview: 10+ messages / expand[flat|nested] mbox.gz Atom feed top
2024-11-15 16:36 [PATCH net-next] net: reformat kdoc return statements Jakub Kicinski
2024-11-15 16:45 ` Johannes Berg
2024-11-15 18:46 ` Jakub Kicinski
2024-11-16 14:28 ` Richard Cochran
2024-11-16 16:23 ` Russell King (Oracle) [this message]
2024-11-19 0:33 ` Jakub Kicinski
2024-11-19 14:42 ` Jonathan Corbet
2024-11-18 0:51 ` Sergey Ryazanov
2024-11-18 10:32 ` Edward Cree
2024-11-19 9:07 ` Alexandra Winter
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=ZzjHH-L-ylLe0YhU@shell.armlinux.org.uk \
--to=linux@armlinux.org.uk \
--cc=davem@davemloft.net \
--cc=dsahern@kernel.org \
--cc=ecree.xilinx@gmail.com \
--cc=edumazet@google.com \
--cc=hawk@kernel.org \
--cc=ilias.apalodimas@linaro.org \
--cc=jhs@mojatatu.com \
--cc=jiri@resnulli.us \
--cc=johannes@sipsolutions.net \
--cc=kuba@kernel.org \
--cc=linux-wireless@vger.kernel.org \
--cc=loic.poulain@linaro.org \
--cc=netdev@vger.kernel.org \
--cc=netfilter-devel@vger.kernel.org \
--cc=pabeni@redhat.com \
--cc=pablo@netfilter.org \
--cc=przemyslaw.kitszel@intel.com \
--cc=richardcochran@gmail.com \
--cc=ryazanov.s.a@gmail.com \
--cc=wintera@linux.ibm.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.