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

[Jonathan Corbet <corbet@lwn.net>]

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.

> 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.

Thanks,

jon