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.


Oleksij Rempel (3):
  tools: ynl-gen: generate kdoc for attribute enums
  net: ynl: add generated kdoc to UAPI headers
  Documentation: net: add flow control guide and document ethtool API

 Documentation/netlink/specs/ethtool.yaml      |  27 ++
 Documentation/networking/flow_control.rst     | 373 ++++++++++++++++++
 Documentation/networking/index.rst            |   1 +
 Documentation/networking/phy.rst              |  12 +-
 include/linux/ethtool.h                       |  45 ++-
 include/uapi/linux/dpll.h                     |  30 ++
 .../uapi/linux/ethtool_netlink_generated.h    |  57 ++-
 include/uapi/linux/if_team.h                  |  11 +
 include/uapi/linux/net_shaper.h               |  50 +++
 include/uapi/linux/netdev.h                   | 165 ++++++++
 include/uapi/linux/ovpn.h                     |  62 +++
 net/dcb/dcbnl.c                               |   2 +
 net/ethtool/pause.c                           |   4 +
 tools/include/uapi/linux/netdev.h             | 165 ++++++++
 tools/net/ynl/pyynl/ynl_gen_c.py              |  23 ++
 15 files changed, 1012 insertions(+), 15 deletions(-)
 create mode 100644 Documentation/networking/flow_control.rst

--
2.47.3

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?

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 |

On Wed, 17 Sep 2025 12:12:22 +0200 Oleksij Rempel wrote:
> 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.

We can adapt our approach to the needs as we go. But yes, my
recollection of the series was that there wasn't actually many
touchpoints here between the generated kdoc and your newly written
docs at this stage. So let's defer rendering into the uAPI headers.