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>

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 | 2962 ++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 2941 insertions(+), 21 deletions(-)

-- 
2.34.1

On Thu, Oct 30, 2025 at 8:26 PM Jianyun Gao <jianyungao89@gmail.com> wrote:
>
> 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

You or AI ?
The whole thing looks like AI generated garbage.
Sorry, but no.

pw-bot: cr

I'm not an AI !

Although the Doxygen docs added in this patch series were assisted by
AI, they were still checked by myself.
You know, this is also a tedious task. The reason why I wanted to do
this job is that I think adding these documentation-style comments is
meaningful and can help some beginners.

However, if you don't like it, I will stop.

Anyway, thank you for your prompt reply.

Thanks
Jianyun

On Fri, Oct 31, 2025 at 10:30 PM Alexei Starovoitov
<alexei.starovoitov@gmail.com> wrote:
>
> On Thu, Oct 30, 2025 at 8:26 PM Jianyun Gao <jianyungao89@gmail.com> wrote:
> >
> > 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
>
> You or AI ?
> The whole thing looks like AI generated garbage.
> Sorry, but no.
>
> pw-bot: cr