On Mon, Oct 4, 2021 at 6:00 PM Song Liu <song@xxxxxxxxxx> wrote: > > On Mon, Oct 4, 2021 at 4:51 PM grantseltzer <grantseltzer@xxxxxxxxx> wrote: > > > > From: Grant Seltzer <grantseltzer@xxxxxxxxx> > > > > This adds a section to the documentation for libbpf > > naming convention which describes how to document > > API features in libbpf, specifically the format of > > which API doc comments need to conform to. > > > > Signed-off-by: Grant Seltzer <grantseltzer@xxxxxxxxx> > > Acked-by: Song Liu <songliubraving@xxxxxx> > Applied to bpf-next, thanks. I've fixed the example block comment indentation (it was off by one space for all but the first line). I also noticed that vim syntax highlighting were treating '/**' as something special, so I added escaping: '/\*\*', but it's not easy for me to serve html from my dev server, so not sure if that renders ok. At least `make htmldocs` didn't complain. BTW, as we'll have (hopefully) more contributions to libbpf docs, it would be nice to integrate `make htmldocs` "check" into selftests/bpf's Makefile. Can you please see if that's possible? Ideally we'd only build docs inside Documentation/bpf to speed things up. Seems like we currently have one error/warning there, so we are in a pretty good shape already, but playing a proactive defense here seems like a prudent approach? > > --- > > .../bpf/libbpf/libbpf_naming_convention.rst | 40 +++++++++++++++++++ > > 1 file changed, 40 insertions(+) > > > > diff --git a/Documentation/bpf/libbpf/libbpf_naming_convention.rst b/Documentation/bpf/libbpf/libbpf_naming_convention.rst > > index 9c68d5014ff1..5f42f172987a 100644 > > --- a/Documentation/bpf/libbpf/libbpf_naming_convention.rst > > +++ b/Documentation/bpf/libbpf/libbpf_naming_convention.rst > > @@ -150,6 +150,46 @@ mirror of the mainline's version of libbpf for a stand-alone build. > > However, all changes to libbpf's code base must be upstreamed through > > the mainline kernel tree. > > > > + > > +API documentation convention > > +============================ > > + > > +The libbpf API is documented via comments above definitions in > > +header files. These comments can be rendered by doxygen and sphinx > > +for well organized html output. This section describes the > > +convention in which these comments should be formated. > > + > > +Here is an example from btf.h: > > + > > +.. code-block:: c > > + > > + /** > > + * @brief **btf__new()** creates a new instance of a BTF object from the raw > > + * bytes of an ELF's BTF section > > + * @param data raw bytes > > + * @param size number of bytes passed in `data` > > + * @return new BTF object instance which has to be eventually freed with > > + * **btf__free()** > > + * > > + * On error, error-code-encoded-as-pointer is returned, not a NULL. To extract > > + * error code from such a pointer `libbpf_get_error()` should be used. If > > + * `libbpf_set_strict_mode(LIBBPF_STRICT_CLEAN_PTRS)` is enabled, NULL is > > + * returned on error instead. In both cases thread-local `errno` variable is > > + * always set to error code as well. > > + */ > > + > > +The comment must start with a block comment of the form '/**'. > > + > > +The documentation always starts with a @brief directive. This line is a short > > +description about this API. It starts with the name of the API, denoted in bold > > +like so: **api_name**. Please include an open and close parenthesis if this is a > > +function. Follow with the short description of the API. A longer form description > > +can be added below the last directive, at the bottom of the comment. > > + > > +Parameters are denoted with the @param directive, there should be one for each > > +parameter. If this is a function with a non-void return, use the @return directive > > +to document it. > > + > > License > > ------------------- > > > > -- > > 2.31.1 > >
