1. Patchew
  2. MPTCP
  3. View series

[PATCH mptcp-next] mptcp: fix kdoc warnings

Matthieu Baerts (NGI0) posted 1 patch 1 week, 1 day ago
Patches applied successfully (tree, apply log)
git fetch https://github.com/multipath-tcp/mptcp_net-next tags/patchew/20260130-mptcp-fix-kdoc-v1-1-a391da37f1ad@kernel.org
include/uapi/linux/mptcp_pm.h |  2 +-
net/mptcp/token.c             | 16 +++++++++-------
2 files changed, 10 insertions(+), 8 deletions(-)
[PATCH mptcp-next] mptcp: fix kdoc warnings
Posted by Matthieu Baerts (NGI0) 1 week, 1 day ago 
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.

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)

---
base-commit: 9eafdb3251fecf25d365143d1a7da2dca70f181f
change-id: 20260130-mptcp-fix-kdoc-eb08ff6f17ca

Best regards,
-- 
Matthieu Baerts (NGI0) <matttbe@kernel.org>
Re: [PATCH mptcp-next] mptcp: fix kdoc warnings
Posted by MPTCP CI 1 week, 1 day ago 
Hi Matthieu,

Thank you for your modifications, that's great!

Our CI did some validations and here is its report:

- KVM Validation: normal (except selftest_mptcp_join): Unstable: 1 failed test(s): selftest_simult_flows 🔴
- KVM Validation: normal (only selftest_mptcp_join): Success! ✅
- KVM Validation: debug (except selftest_mptcp_join): Unstable: 1 failed test(s): packetdrill_dss 🔴
- KVM Validation: debug (only selftest_mptcp_join): Success! ✅
- KVM Validation: btf-normal (only bpftest_all): Success! ✅
- KVM Validation: btf-debug (only bpftest_all): Success! ✅
- Task: https://github.com/multipath-tcp/mptcp_net-next/actions/runs/21509881155

Initiator: Matthieu Baerts (NGI0)
Commits: https://github.com/multipath-tcp/mptcp_net-next/commits/e7d299bab1af
Patchwork: https://patchwork.kernel.org/project/mptcp/list/?series=1048865


If there are some issues, you can reproduce them using the same environment as
the one used by the CI thanks to a docker image, e.g.:

    $ cd [kernel source code]
    $ docker run -v "${PWD}:${PWD}:rw" -w "${PWD}" --privileged --rm -it \
        --pull always mptcp/mptcp-upstream-virtme-docker:latest \
        auto-normal

For more details:

    https://github.com/multipath-tcp/mptcp-upstream-virtme-docker


Please note that despite all the efforts that have been already done to have a
stable tests suite when executed on a public CI like here, it is possible some
reported issues are not due to your modifications. Still, do not hesitate to
help us improve that ;-)

Cheers,
MPTCP GH Action bot
Bot operated by Matthieu Baerts (NGI0 Core)
Re: [PATCH mptcp-next] mptcp: fix kdoc warnings
Posted by MPTCP CI 1 week, 1 day ago 
Hi Matthieu,

Thank you for your modifications, that's great!

Our CI did some validations and here is its report:

- KVM Validation: normal (except selftest_mptcp_join): Unstable: 1 failed test(s): selftest_simult_flows 🔴
- KVM Validation: normal (only selftest_mptcp_join): Success! ✅
- KVM Validation: debug (except selftest_mptcp_join): Success! ✅
- KVM Validation: debug (only selftest_mptcp_join): Success! ✅
- KVM Validation: btf-normal (only bpftest_all): Critical: Boot failures ❌
- KVM Validation: btf-debug (only bpftest_all): Success! ✅
- Task: https://github.com/multipath-tcp/mptcp_net-next/actions/runs/21508880773

Initiator: Patchew Applier
Commits: https://github.com/multipath-tcp/mptcp_net-next/commits/855afa251f5d
Patchwork: https://patchwork.kernel.org/project/mptcp/list/?series=1048865


If there are some issues, you can reproduce them using the same environment as
the one used by the CI thanks to a docker image, e.g.:

    $ cd [kernel source code]
    $ docker run -v "${PWD}:${PWD}:rw" -w "${PWD}" --privileged --rm -it \
        --pull always mptcp/mptcp-upstream-virtme-docker:latest \
        auto-normal

For more details:

    https://github.com/multipath-tcp/mptcp-upstream-virtme-docker


Please note that despite all the efforts that have been already done to have a
stable tests suite when executed on a public CI like here, it is possible some
reported issues are not due to your modifications. Still, do not hesitate to
help us improve that ;-)

Cheers,
MPTCP GH Action bot
Bot operated by Matthieu Baerts (NGI0 Core)
Re: [PATCH mptcp-next] mptcp: fix kdoc warnings
Posted by Geliang Tang 1 week, 1 day ago 
Hi Matt,

Thanks for this fix.

On Fri, 2026-01-30 at 08:52 +0100, 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.
> 
> Signed-off-by: Matthieu Baerts (NGI0) <matttbe@kernel.org>

Looks good to me.

Reviewed-by: Geliang Tang <geliang@kernel.org>

-Geliang

> ---
>  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)
> 
> ---
> base-commit: 9eafdb3251fecf25d365143d1a7da2dca70f181f
> change-id: 20260130-mptcp-fix-kdoc-eb08ff6f17ca
> 
> Best regards,
Re: [PATCH mptcp-next] mptcp: fix kdoc warnings
Posted by Matthieu Baerts 1 week, 1 day ago 
Hi Geliang,

On 30/01/2026 09:28, Geliang Tang wrote:
> On Fri, 2026-01-30 at 08:52 +0100, Matthieu Baerts (NGI0) wrote:
>> The following warnings were visible:

(...)
>> 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.
>>
>> Signed-off-by: Matthieu Baerts (NGI0) <matttbe@kernel.org>
> 
> Looks good to me.

Thank you for the review!

Note that the CI now checks these warnings, e.g.:

https://github.com/multipath-tcp/mptcp_net-next/actions/runs/21509881177


Now in our tree:

New patches for t/upstream:
- 3d0ed4124117: mptcp: fix kdoc warnings
- Results: 803afbaeada9..50e7f60d4f2a (export)

Tests are now in progress:

- export:
https://github.com/multipath-tcp/mptcp_net-next/commit/9538a224bbca2b776a98b1384c7b8b0156e5dc89/checks

Cheers,
Matt
-- 
Sponsored by the NGI0 Core fund.

Patchew 2.1-devel-b67e4c2

© 2016 - 2026 Red Hat, Inc.