Hi,
Background:
While consulting libbpf's online documentation at https://libbpf.readthedocs.io/
I noticed that many public LIBBPF_API helpers in tools/lib/bpf/bpf.h either
lacked descriptions entirely or had very minimal/fragmented information. This
makes it harder for both new and experienced users to understand semantics,
error handling, privilege requirements, flag usage, and concurrency aspects of
these APIs. To improve discoverability and self-service learning, I prepared a
series adding consistent Doxygen comment blocks for all currently exported
LIBBPF_API interfaces.
Goals of this series:
- Provide structured @brief, parameter, return, and common error descriptions.
- Clarify behavior of flags (e.g. BPF_F_LOCK, batch operation semantics).
- Note privilege/capability considerations where relevant.
- Normalize wording of return conventions (0 on success, negative libbpf-style
error == -errno) without changing actual behavior.
- Improve completeness of generated HTML/PDF docs produced via Doxygen.
- Pure documentation; no code logic, ABI, or symbol changes.
Patch breakdown:
1/5 libbpf: Add Doxygen documentation for bpf_map_* APIs in bpf.h
2/5 libbpf: Add Doxygen documentation for bpf_prog_* APIs in bpf.h
3/5 libbpf: Add Doxygen documentation for bpf_link_* APIs in bpf.h
4/5 libbpf: Add Doxygen documentation for bpf_obj_* APIs in bpf.h
5/5 libbpf: Add Doxygen documentation for btf/iter etc. in bpf.h
Diffstat (approximate):
tools/lib/bpf/bpf.h | 2962 ++++++++++++++++++++++++++++++++++++++++++-
1 file changed, 2941 insertions(+), 21 deletions(-)
Thanks for reviewing.
Signed-off-by: Jianyun Gao <jianyungao89@gmail.com>
---
v1->v2:
- Fixed compilation error caused by embedded literal "/*" inside a
comment (rephrased/escaped).
- Refined bpf_map_* return value docs: explicit non-negative success
vs negative -errno failures.
- Fixed the non-ASCII characters in the patches.
The v1 is here:
https://lore.kernel.org/lkml/20251031032627.1414462-1-jianyungao89@gmail.com/
---
Jianyun Gao (5):
libbpf: Add doxygen documentation for bpf_map_* APIs in bpf.h
libbpf: Add doxygen documentation for bpf_prog_* APIs in bpf.h
libbpf: Add doxygen documentation for bpf_link_* APIs in bpf.h
libbpf: Add doxygen documentation for bpf_obj_* APIs in bpf.h
libbpf: Add doxygen documentation for btf/iter etc. in bpf.h
tools/lib/bpf/bpf.h | 2967 ++++++++++++++++++++++++++++++++++++++++++-
1 file changed, 2946 insertions(+), 21 deletions(-)
--
2.34.1