linux-kernel - Re: [PATCH net-next v4 0/3] Documentation and ynl: add flow control

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [day] [month] [year] [list]

Message-ID: <aMqJhl2swbkiYx_p@pengutronix.de>
Date: Wed, 17 Sep 2025 12:12:22 +0200
From: Oleksij Rempel <o.rempel@...gutronix.de>
To: Jakub Kicinski <kuba@...nel.org>
Cc: Andrew Lunn <andrew@...n.ch>, Vladimir Oltean <vladimir.oltean@....com>,
	Alexei Starovoitov <ast@...nel.org>,
	Russell King <linux@...linux.org.uk>,
	Eric Dumazet <edumazet@...gle.com>, Rob Herring <robh@...nel.org>,
	Florian Fainelli <f.fainelli@...il.com>,
	Donald Hunter <donald.hunter@...il.com>,
	Daniel Borkmann <daniel@...earbox.net>,
	Jonathan Corbet <corbet@....net>,
	John Fastabend <john.fastabend@...il.com>,
	Lukasz Majewski <lukma@...x.de>,
	Maxime Chevallier <maxime.chevallier@...tlin.com>,
	Stanislav Fomichev <sdf@...ichev.me>,
	Paolo Abeni <pabeni@...hat.com>, Jiri Pirko <jiri@...nulli.us>,
	Jesper Dangaard Brouer <hawk@...nel.org>,
	Divya.Koppera@...rochip.com,
	Kory Maincent <kory.maincent@...tlin.com>,
	Vadim Fedorenko <vadim.fedorenko@...ux.dev>, netdev@...r.kernel.org,
	Sabrina Dubroca <sd@...asysnail.net>, linux-kernel@...r.kernel.org,
	kernel@...gutronix.de, Krzysztof Kozlowski <krzk+dt@...nel.org>,
	"David S. Miller" <davem@...emloft.net>,
	Heiner Kallweit <hkallweit1@...il.com>
Subject: Re: [PATCH net-next v4 0/3] Documentation and ynl: add flow control

On Tue, Sep 09, 2025 at 02:32:56PM -0700, Jakub Kicinski wrote:
> On Tue,  9 Sep 2025 09:22:09 +0200 Oleksij Rempel wrote:
> > This series improves kernel documentation around Ethernet flow control
> > and enhances the ynl tooling to generate kernel-doc comments for
> > attribute enums.
> > 
> > Patch 1 extends the ynl generator to emit kdoc for enums based on YAML
> > attribute documentation.
> > Patch 2 regenerates all affected UAPI headers (dpll, ethtool, team,
> > net_shaper, netdev, ovpn) so that attribute enums now carry kernel-doc.
> > Patch 3 adds a new flow_control.rst document and annotates the ethtool
> > pause/pause-stat YAML definitions, relying on the kdoc generation
> > support from the earlier patches.
> 
> The reason we don't render the kdoc today is that I thought it's far
> more useful to focus on the direct ReST generation. I think some of 
> the docs are not rendered, and other may be garbled, but the main
> structure of the documentation works quite well:
> 
>   https://docs.kernel.org/next/netlink/specs/dpll.html
> 
> Could you spell out the motivation for this change a little more?

The reason I went down the kdoc-in-UAPI route is mostly historical.
When I first started writing the flow control documentation, reviewers
pointed out that the UAPI parts should be documented in the header
files.  Since these headers are generated from YAML, the natural way was
to move  the docstrings into the YAML and let the generator emit them.
One step led  to another, and we ended up with this change.

I don’t have a strong preference for where the documentation lives, my
primary goal was to avoid duplicating text and make sure the UAPI enums
for pause / pause-stat are self-describing. If the consensus is that we
should concentrate on ReST output only, I’m happy to reduce the scope of
this series and drop the kernel-doc emission. The actual motivation of
my  series is to add flow_control.rst and document the ethtool API
there.

So if you prefer, I can respin with just the flow_control.rst and YAML  
annotations, and skip the generator changes.

Oleksij
-- 
Pengutronix e.K.                           |                             |
Steuerwalder Str. 21                       | http://www.pengutronix.de/  |
31137 Hildesheim, Germany                  | Phone: +49-5121-206917-0    |
Amtsgericht Hildesheim, HRA 2686           | Fax:   +49-5121-206917-5555 |