Akira Yokosawa <akiyks@xxxxxxxxx> 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
