[PATCH net-next] net_shaper: fix net_shaper_ops kernel-doc

[PATCH net-next] net_shaper: fix net_shaper_ops kernel-doc

[Karl Mehltretter]

Everything from the "Driver ops vs uAPI" heading onward is dropped from
the rendered net_shaper_ops documentation. Older Docutils versions do so
silently, while Docutils 0.22 reports the nested headings and adjacent
list as invalid.

Use bold labels and correct the list indentation.

Fixes: 16812d9674d4 ("net_shaper: remove incorrect comment about group leaves")
Fixes: 26bc4cfb1737 ("net_shaper: clarify the kernel API / comments")
Assisted-by: Codex:gpt-5.6-sol
Signed-off-by: Karl Mehltretter <kmehltretter@gmail.com>
---
The omission is visible in the current linux-next generated documentation:
https://www.kernel.org/doc/html/next/networking/kapi.html#c.net_shaper_ops

Tested with Sphinx 9.1.0 and Docutils 0.22.4:
  make SPHINXDIRS=networking htmldocs

 include/net/net_shaper.h | 17 +++++++++--------
 1 file changed, 9 insertions(+), 8 deletions(-)

diff --git a/include/net/net_shaper.h b/include/net/net_shaper.h
index 05cb625b0fe54..a2eb616a19fd0 100644
--- a/include/net/net_shaper.h
+++ b/include/net/net_shaper.h
@@ -73,20 +73,21 @@ struct net_shaper {
  * Each shaper is uniquely identified within the device with a 'handle'
  * comprising the shaper scope and a scope-specific id.
  *
- * Driver ops vs uAPI
- * ------------------
+ * **Driver ops vs uAPI**
+ *
  * Members of the driver ops mirror the Netlink uAPI but driver calls do not
  * map 1:1 to user calls. Drivers need to be careful when assuming that calls
  * disallowed at the uAPI level will never be made at the driver level.
  * The shaper core performs automatic reparenting and cleanup, generating
  * additional calls. Notably:
- *  - @group calls in the driver facing API may have nodes as leaves (user is
- *    only allowed to construct groups with queues as leaves)
- *  - @group calls may update leaf's parent if the parent is about
- *    to be removed (re-parenting nodes explicitly is not supported in the uAPI)
  *
- * Implicit creation
- * -----------------
+ * - @group calls in the driver facing API may have nodes as leaves (user is
+ *   only allowed to construct groups with queues as leaves)
+ * - @group calls may update leaf's parent if the parent is about
+ *   to be removed (re-parenting nodes explicitly is not supported in the uAPI)
+ *
+ * **Implicit creation**
+ *
  * Shapers are created implicitly, meaning that @set and @group operations
  * are called both for existing and new shapers. The driver has to infer
  * whether the operation is an update or a creation by tracking the handles.

base-commit: 3205699d79f262412c1be7fc1c04066610d3cd52
-- 
2.53.0

Re: [PATCH net-next] net_shaper: fix net_shaper_ops kernel-doc

[Jakub Kicinski]

Adding the missing CC of linux-doc

On Thu, 13 Aug 2026 21:21:31 +0200 Karl Mehltretter wrote:
> Everything from the "Driver ops vs uAPI" heading onward is dropped from
> the rendered net_shaper_ops documentation. Older Docutils versions do so
> silently, while Docutils 0.22 reports the nested headings and adjacent
> list as invalid.

Isn't this a problem in kernel-doc extraction / how we embed it for
rendering? Heading are quite useful and IMHO far more natural to use.
My understanding was that kdoc should be able to use basic ReST
formatting.

Ack on the list indent fix

> Use bold labels and correct the list indentation.
> 
> Fixes: 16812d9674d4 ("net_shaper: remove incorrect comment about group leaves")
> Fixes: 26bc4cfb1737 ("net_shaper: clarify the kernel API / comments")

This is a doc patch, please don't sprinkle Fixes tag on patches which
don't fix bugs.

> Assisted-by: Codex:gpt-5.6-sol
> Signed-off-by: Karl Mehltretter <kmehltretter@gmail.com>
> ---
> The omission is visible in the current linux-next generated documentation:
> https://www.kernel.org/doc/html/next/networking/kapi.html#c.net_shaper_ops
> 
> Tested with Sphinx 9.1.0 and Docutils 0.22.4:
>   make SPHINXDIRS=networking htmldocs
> 
>  include/net/net_shaper.h | 17 +++++++++--------
>  1 file changed, 9 insertions(+), 8 deletions(-)
> 
> diff --git a/include/net/net_shaper.h b/include/net/net_shaper.h
> index 05cb625b0fe54..a2eb616a19fd0 100644
> --- a/include/net/net_shaper.h
> +++ b/include/net/net_shaper.h
> @@ -73,20 +73,21 @@ struct net_shaper {
>   * Each shaper is uniquely identified within the device with a 'handle'
>   * comprising the shaper scope and a scope-specific id.
>   *
> - * Driver ops vs uAPI
> - * ------------------
> + * **Driver ops vs uAPI**
> + *
>   * Members of the driver ops mirror the Netlink uAPI but driver calls do not
>   * map 1:1 to user calls. Drivers need to be careful when assuming that calls
>   * disallowed at the uAPI level will never be made at the driver level.
>   * The shaper core performs automatic reparenting and cleanup, generating
>   * additional calls. Notably:
> - *  - @group calls in the driver facing API may have nodes as leaves (user is
> - *    only allowed to construct groups with queues as leaves)
> - *  - @group calls may update leaf's parent if the parent is about
> - *    to be removed (re-parenting nodes explicitly is not supported in the uAPI)
>   *
> - * Implicit creation
> - * -----------------
> + * - @group calls in the driver facing API may have nodes as leaves (user is
> + *   only allowed to construct groups with queues as leaves)
> + * - @group calls may update leaf's parent if the parent is about
> + *   to be removed (re-parenting nodes explicitly is not supported in the uAPI)
> + *
> + * **Implicit creation**
> + *
>   * Shapers are created implicitly, meaning that @set and @group operations
>   * are called both for existing and new shapers. The driver has to infer
>   * whether the operation is an update or a creation by tracking the handles.
> 
> base-commit: 3205699d79f262412c1be7fc1c04066610d3cd52