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

[Jakub Kicinski <kuba@kernel.org>]

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.