The following warnings were visible:
$ ./scripts/kernel-doc -Wall -none \
net/mptcp/ include/net/mptcp.h include/uapi/linux/mptcp*.h \
include/trace/events/mptcp.h
Warning: net/mptcp/token.c:108 No description found for return value of 'mptcp_token_new_request'
Warning: net/mptcp/token.c:151 No description found for return value of 'mptcp_token_new_connect'
Warning: net/mptcp/token.c:246 No description found for return value of 'mptcp_token_get_sock'
Warning: net/mptcp/token.c:298 No description found for return value of 'mptcp_token_iter_next'
Warning: net/mptcp/protocol.c:4431 No description found for return value of 'mptcp_splice_read'
Warning: include/uapi/linux/mptcp_pm.h:13 missing initial short description on line:
* enum mptcp_event_type
Address all of them: either by using the 'Return:' keyword, or by adding
a missing initial short description.
The MPTCP CI will soon report issues with kdoc to avoid introducing new
issues and being flagged by the Netdev CI.
Reviewed-by: Geliang Tang <geliang@kernel.org>
Signed-off-by: Matthieu Baerts (NGI0) <matttbe@kernel.org>
---
include/uapi/linux/mptcp_pm.h | 2 +-
net/mptcp/token.c | 16 +++++++++-------
2 files changed, 10 insertions(+), 8 deletions(-)
diff --git a/include/uapi/linux/mptcp_pm.h b/include/uapi/linux/mptcp_pm.h
index c97d060ee90b..fe9863d75350 100644
--- a/include/uapi/linux/mptcp_pm.h
+++ b/include/uapi/linux/mptcp_pm.h
@@ -11,7 +11,7 @@
#define MPTCP_PM_VER 1
/**
- * enum mptcp_event_type
+ * enum mptcp_event_type - Netlink MPTCP event types
* @MPTCP_EVENT_UNSPEC: unused event
* @MPTCP_EVENT_CREATED: A new MPTCP connection has been created. It is the
* good time to allocate memory and send ADD_ADDR if needed. Depending on the
diff --git a/net/mptcp/token.c b/net/mptcp/token.c
index 5bb924534387..f1a50f367add 100644
--- a/net/mptcp/token.c
+++ b/net/mptcp/token.c
@@ -103,7 +103,7 @@ static void mptcp_crypto_key_gen_sha(u64 *key, u32 *token, u64 *idsn)
* It creates a unique token to identify the new mptcp connection,
* a secret local key and the initial data sequence number (idsn).
*
- * Returns 0 on success.
+ * Return: 0 on success.
*/
int mptcp_token_new_request(struct request_sock *req)
{
@@ -146,7 +146,7 @@ int mptcp_token_new_request(struct request_sock *req)
* the computed token at a later time, this is needed to process
* join requests.
*
- * returns 0 on success.
+ * Return: 0 on success.
*/
int mptcp_token_new_connect(struct sock *ssk)
{
@@ -241,7 +241,7 @@ bool mptcp_token_exists(u32 token)
* This function returns the mptcp connection structure with the given token.
* A reference count on the mptcp socket returned is taken.
*
- * returns NULL if no connection with the given token value exists.
+ * Return: NULL if no connection with the given token value exists.
*/
struct mptcp_sock *mptcp_token_get_sock(struct net *net, u32 token)
{
@@ -288,11 +288,13 @@ EXPORT_SYMBOL_GPL(mptcp_token_get_sock);
* @s_slot: start slot number
* @s_num: start number inside the given lock
*
- * This function returns the first mptcp connection structure found inside the
- * token container starting from the specified position, or NULL.
+ * Description:
+ * On successful iteration, the iterator is moved to the next position and a
+ * reference to the returned socket is acquired.
*
- * On successful iteration, the iterator is moved to the next position and
- * a reference to the returned socket is acquired.
+ * Return:
+ * The first mptcp connection structure found inside the token container
+ * starting from the specified position, or NULL.
*/
struct mptcp_sock *mptcp_token_iter_next(const struct net *net, long *s_slot,
long *s_num)
--
2.51.0Hello, On 04/02/2026 17:57, Matthieu Baerts (NGI0) wrote: > The following warnings were visible: > > $ ./scripts/kernel-doc -Wall -none \ > net/mptcp/ include/net/mptcp.h include/uapi/linux/mptcp*.h \ > include/trace/events/mptcp.h > Warning: net/mptcp/token.c:108 No description found for return value of 'mptcp_token_new_request' > Warning: net/mptcp/token.c:151 No description found for return value of 'mptcp_token_new_connect' > Warning: net/mptcp/token.c:246 No description found for return value of 'mptcp_token_get_sock' > Warning: net/mptcp/token.c:298 No description found for return value of 'mptcp_token_iter_next' > Warning: net/mptcp/protocol.c:4431 No description found for return value of 'mptcp_splice_read' > Warning: include/uapi/linux/mptcp_pm.h:13 missing initial short description on line: > * enum mptcp_event_type > > Address all of them: either by using the 'Return:' keyword, or by adding > a missing initial short description. > > The MPTCP CI will soon report issues with kdoc to avoid introducing new > issues and being flagged by the Netdev CI. > > Reviewed-by: Geliang Tang <geliang@kernel.org> > Signed-off-by: Matthieu Baerts (NGI0) <matttbe@kernel.org> > --- > include/uapi/linux/mptcp_pm.h | 2 +- > net/mptcp/token.c | 16 +++++++++------- > 2 files changed, 10 insertions(+), 8 deletions(-) > > diff --git a/include/uapi/linux/mptcp_pm.h b/include/uapi/linux/mptcp_pm.h > index c97d060ee90b..fe9863d75350 100644 > --- a/include/uapi/linux/mptcp_pm.h > +++ b/include/uapi/linux/mptcp_pm.h > @@ -11,7 +11,7 @@ > #define MPTCP_PM_VER 1 > > /** > - * enum mptcp_event_type > + * enum mptcp_event_type - Netlink MPTCP event types I forgot that this file was auto-generated from a YAML file. Sorry for the noise, I will send a v2 also adapting the YAML file. pw-bot: cr Cheers, Matt -- Sponsored by the NGI0 Core fund.
On Thu, 5 Feb 2026 11:56:39 +0100 Matthieu Baerts wrote: > > diff --git a/include/uapi/linux/mptcp_pm.h b/include/uapi/linux/mptcp_pm.h > > index c97d060ee90b..fe9863d75350 100644 > > --- a/include/uapi/linux/mptcp_pm.h > > +++ b/include/uapi/linux/mptcp_pm.h > > @@ -11,7 +11,7 @@ > > #define MPTCP_PM_VER 1 > > > > /** > > - * enum mptcp_event_type > > + * enum mptcp_event_type - Netlink MPTCP event types > > I forgot that this file was auto-generated from a YAML file. > > Sorry for the noise, I will send a v2 also adapting the YAML file. Hm, do we need some clever way to teach the codegen about short descriptions?
Hi Jakub, 05 Feb 2026 16:56:08 Jakub Kicinski <kuba@kernel.org>: > On Thu, 5 Feb 2026 11:56:39 +0100 Matthieu Baerts wrote: >>> diff --git a/include/uapi/linux/mptcp_pm.h b/include/uapi/linux/mptcp_pm.h >>> index c97d060ee90b..fe9863d75350 100644 >>> --- a/include/uapi/linux/mptcp_pm.h >>> +++ b/include/uapi/linux/mptcp_pm.h >>> @@ -11,7 +11,7 @@ >>> #define MPTCP_PM_VER 1 >>> >>> /** >>> - * enum mptcp_event_type >>> + * enum mptcp_event_type - Netlink MPTCP event types >> >> I forgot that this file was auto-generated from a YAML file. >> >> Sorry for the noise, I will send a v2 also adapting the YAML file. > > Hm, do we need some clever way to teach the codegen about short > descriptions? In my case, there was no "doc" for this enum: https://lore.kernel.org/20260205-mptcp-fix-kdoc-yml-v1-1-9858c4b7baf6@kernel.org Adding it fixes the kdoc warning. Do you mean that the codegen should add a short description even if "doc" is not set? Cheers, Matt
On Thu, 5 Feb 2026 17:42:24 +0100 Matthieu Baerts wrote: > >> I forgot that this file was auto-generated from a YAML file. > >> > >> Sorry for the noise, I will send a v2 also adapting the YAML file. > > > > Hm, do we need some clever way to teach the codegen about short > > descriptions? > > In my case, there was no "doc" for this enum: > > https://lore.kernel.org/20260205-mptcp-fix-kdoc-yml-v1-1-9858c4b7baf6@kernel.org > > Adding it fixes the kdoc warning. > > Do you mean that the codegen should add a short description even if > "doc" is not set? Ah, ignore me. I thought we did: /** * $type * @member: $member-doc * @member: $member-doc * * $type-doc */ But looks like we put the type doc upfront and wrap, so perhaps not pretty but shouldn't run afoul of kdoc rules.
On 2/4/26 8:57 AM, Matthieu Baerts (NGI0) wrote: > The following warnings were visible: > > $ ./scripts/kernel-doc -Wall -none \ > net/mptcp/ include/net/mptcp.h include/uapi/linux/mptcp*.h \ > include/trace/events/mptcp.h > Warning: net/mptcp/token.c:108 No description found for return value of 'mptcp_token_new_request' > Warning: net/mptcp/token.c:151 No description found for return value of 'mptcp_token_new_connect' > Warning: net/mptcp/token.c:246 No description found for return value of 'mptcp_token_get_sock' > Warning: net/mptcp/token.c:298 No description found for return value of 'mptcp_token_iter_next' > Warning: net/mptcp/protocol.c:4431 No description found for return value of 'mptcp_splice_read' > Warning: include/uapi/linux/mptcp_pm.h:13 missing initial short description on line: > * enum mptcp_event_type > > Address all of them: either by using the 'Return:' keyword, or by adding > a missing initial short description. > > The MPTCP CI will soon report issues with kdoc to avoid introducing new > issues and being flagged by the Netdev CI. > > Reviewed-by: Geliang Tang <geliang@kernel.org> > Signed-off-by: Matthieu Baerts (NGI0) <matttbe@kernel.org> > --- > include/uapi/linux/mptcp_pm.h | 2 +- > net/mptcp/token.c | 16 +++++++++------- > 2 files changed, 10 insertions(+), 8 deletions(-) LGTM. Thanks. Reviewed-by: Randy Dunlap <rdunlap@infradead.org> -- ~Randy
© 2016 - 2026 Red Hat, Inc.