Re: [PATCH bpf-next v2 1/1] docs: BPF_MAP_TYPE_XSKMAP

[Donald Hunter <donald.hunter@gmail.com>]

Akira Yokosawa <akiyks@gmail.com> writes:
>
> So you have two declarations of bpf_map_lookup_elem() in map_xskmap.rst.
>
> This will cause "make htmldocs" with Sphinx >=3.1 to emit a warning of:
>
> /linux/Documentation/bpf/map_xskmap.rst:100: WARNING: Duplicate C declaration, also defined at map_xskmap:71.
> Declaration is '.. c:function:: int bpf_map_lookup_elem(int fd, const void *key, void *value)'.
>
> , in addition to a bunch of similar warnings observed at bpf-next:
>
> /linux/Documentation/bpf/map_cpumap.rst:50: WARNING: Duplicate C declaration, also defined at map_array:43.
> Declaration is '.. c:function:: int bpf_map_update_elem(int fd, const void *key, const void *value, __u64 flags);'.
> /linux/Documentation/bpf/map_cpumap.rst:72: WARNING: Duplicate C declaration, also defined at map_array:35.
> Declaration is '.. c:function:: int bpf_map_lookup_elem(int fd, const void *key, void *value);'.
> /linux/Documentation/bpf/map_hash.rst:37: WARNING: Duplicate C declaration, also defined at map_array:43.
> Declaration is '.. c:function:: long bpf_map_update_elem(struct bpf_map *map, const void *key, const void *value, u64 flags)'.
> ... [bunch of similar warnings]

That's unfortunate, and I'm responsible for some of those. Not sure how
we'd know to check for warnings with Sphinx >= 3.1 when
Documentation/doc-guide/sphinx.rst and
Documentation/sphinx/requirements.txt both specify version 2.4.4

> You might want to say you don't care, but they would annoy those
> who do test "make htmldocs".
>
> So let me explain why sphinx complains.
>
> C domain declarations in kernel documentation are for kernel APIs.
> By default, c:function declarations belong to the top-level namespace,
> which is intended for kernel APIs.
>
> IIUC, most APIs described in map*.rst files don't belong to kernel.
> So I think the way to go is to use the c:namespace directive.
>
> See: https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#namespacing
>
> As mentioned there, namespacing works with Sphinx >=3.1.
> Currently, kernel documentation build scripts support only the
> "c:namespace" directive, which means you can't switch namespaces in the
> middle of a .rst file. This limitation comes from the fact that Sphinx
> 1.7.9 is still in the list for htmldocs at the moment and build scripts
> emulate namespacing for Sphinx <3.1 in a limited way.

What's the reason for keeping support for Sphinx 1.7.9 and pinning to
2.4.4 in Documentation/sphinx/requirements.txt if we want to support
Sphinx >= 3.1? Given that the latest Sphinx release is 5.3.0, and Python
2 support was dropped in Sphinx 2.0.0 it seems that we need to have a
higher minimum version and a higher default version.

> So please avoid putting function declarations of the same name in
> a .rst file.

The same function name, with different signature gets used as a BPF
helper and as a userspace function. We'd really like to be able to
document the semantics of both for a given BPF map type, all on the same
page.

Is there a better way for us to highlight the function signature,
without using the c:function:: directive, since they're not really
function declarations?

> The other duplicate warnings shown above can be silenced by the
> change attached below. It is only as a suggestion and I'm not putting
> a S-o-b tag.
>
> Hope this helps,
>
> Akira