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

[Randy Dunlap]

On 8/14/26 10:14 AM, Jakub Kicinski wrote:
> 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.
> 

I would prefer to also see the actual warning messages in the patch description,
but that's up to the maintainer(s).  (or just one of them would be OK)

Documentation/networking/kapi:107: ../include/net/net_shaper.h:75: ERROR: A level 3 section cannot be used here.

Driver ops vs uAPI
------------------

Established title styles: =/= = -

The parent of level 3 sections cannot be reached. The parser is at section level 3 but the current node has only 0 parent section(s).
One reason may be a high level section used in a directive that parses its content into a base node not attached to the document
(up to Docutils 0.21, these sections were silently dropped). [docutils]
Documentation/networking/kapi:107: ../include/net/net_shaper.h:82: ERROR: Unexpected indentation. [docutils]


I don't know of another reasonable solution for this (although I'm no expert
on ReST), so

Acked-by: Randy Dunlap <rdunlap@xxxxxxxxxxxxx>
Tested-by: Randy Dunlap <rdunlap@xxxxxxxxxxxxx>

Thanks.

>> Assisted-by: Codex:gpt-5.6-sol
>> Signed-off-by: Karl Mehltretter <kmehltretter@xxxxxxxxx>
>> ---
>> 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
> 
>