Re: [PATCH bpf-next 0/3] Autogenerating API documentation

[Grant Seltzer Richman <grantseltzer@gmail.com>]

On Fri, Apr 30, 2021 at 10:22 AM Jonathan Corbet <corbet@lwn.net> wrote:
>
> Grant Seltzer Richman <grantseltzer@gmail.com> writes:
>
> > Hm, yes I do agree that it'd be nice to use existing tooling but I
> > just have a couple concerns for this but please point me in the right
> > direction because i'm sure i'm missing something. I was told to ask on
> > the linux-doc mailing list because you'd have valuable input anway.
> > This is based on reading
> > https://www.kernel.org/doc/html/v4.9/kernel-documentation.html#including-kernel-doc-comments
> >
> > 1. We'd want the ability to pull documentation from the code itself to
> > make it so documentation never falls out of date with code. Based on
> > the docs on kernel.org/doc it seems that we'd have to be explicit with
> > specifying which functions/types are included in an .rst file and
> > submit a patch to update the documentation everytime the libbpf api
> > changes. Perhaps if this isn't a thing already I can figure out how to
> > contribute it.
>
> No, you can tell it to pull out docs for all of the functions in a given
> file.  You only need to name things if you want to narrow things down.

Alright, I will figure out how to do this and adjust the patch
accordingly. My biggest overall goal is making it as easy as possible
to contribute documentation. I think even adding just one doc string
above an API function is a great opportunity for new contributors to
familiarize themselves with the mailing list/patch process.

>
> > 2. Would it be possible (or necessary) to separate libbpf
> > documentation from the kernel readthedocs page since libbpf isn't part
> > of the kernel?
>
> It could certainly be built as a separate "book", as are many of the
> kernel books now.  I could see it as something that gets pulled into the
> user-space API book, but there could also perhaps be an argument made
> for creating a new "libraries" book instead.

Yea if I can figure this out for the libbpf API it'd be great to
replicate it for any API!

>
> Thanks,
>
> jon