Re: [PATCH v2 2/2] docs: netlink: basic introduction to Netlink

[Jakub Kicinski <kuba@kernel.org>]

On Fri, 19 Aug 2022 14:54:48 -0600 Jonathan Corbet wrote:
> Jakub Kicinski <kuba@kernel.org> writes:
> 
> > Provide a bit of a brain dump of netlink related information
> > as documentation. Hopefully this will be useful to people
> > trying to navigate implementing YAML based parsing in languages
> > we won't be able to help with.
> >
> > I started writing this doc while trying to figure out what
> > it'd take to widen the applicability of YAML to good old rtnl,
> > but the doc grew beyond that as it usually happens.
> >
> > In all honesty a lot of this information is new to me as I usually
> > follow the "copy an existing example, drink to forget" process
> > of writing netlink user space, so reviews will be much appreciated.
> >
> > Reviewed-by: Jacob Keller <jacob.e.keller@intel.com>
> > Signed-off-by: Jakub Kicinski <kuba@kernel.org>
> > --
> > Jon, I'm putting this in userspace-api/ I think it fits reasonably
> > well there but please don't hesitate to suggest a better home.  
> 
> That seems like a fine place for it - this is an addition that, I think,
> a lot of people will welcome.
> 
> A couple of nits, feel free to ignore them:
> 
>  - Do you plan to add other netlink documents to that directory in the
>    future?  If not, I'd just make a netlink.rst and not bother with the
>    directory and index.rst.

I do - I'm working on creating protocol specifications (what operations
and attributes family has) in YAML, and at the very least I'll have to
document how to use those specs. And there needs to be some
documentation for the attribute formats.

I've also enlisted help of Peter of the pyroute2 fame to write a Sphinx
plugin which would render the documentation from the YAML specs into
this directory...

>  - I'm not sure that all the :c:member markup buys enough to be worth
>    the clutter.

Right :( I could swear it worked for me in the sk_buff docs, here it
does not actually link to the documentation of the type :S I do like
the consistent formatting tho, so I think I'll keep it either way.

> Regardless, should it be worth something:
> 
> Acked-by: Jonathan Corbet <corbet@lwn.net>
> 
> Thanks for doing this; I've been meaning for years to reverse-engineer
> netlink and write something like this, now I don't have to :)

Thank you! :)