On Fri, Apr 30, 2021 at 10:22 AM Jonathan Corbet <corbet@xxxxxxx> wrote: > > Grant Seltzer Richman <grantseltzer@xxxxxxxxx> 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
