Add sphinx code documentation comments
PATCH v2 1/1 Add sphinx code documentation comments
From: Grant Seltzer <[email protected]>
This adds comments above five functions in btf.h which document their uses. These comments are of a format that doxygen and sphinx can pick up and render. These are rendered by libbpf.readthedocs.org
--- tools/lib/bpf/btf.h | 37 +++++++++++++++++++++++++++++++++++++ 1 file changed, 37 insertions(+)
tools/lib/bpf/btf.h +37 -0
@@ -1,5 +1,6 @@/* SPDX-License-Identifier: (LGPL-2.1 OR BSD-2-Clause) */ /* Copyright (c) 2018 Facebook */ +/*! \file */ #ifndef __LIBBPF_BTF_H#define __LIBBPF_BTF_H
@@ -30,11 +31,47 @@ enum btf_endianness { BTF_BIG_ENDIAN = 1, }; +/** +* @brief **btf__free()** frees all data of a BTF object. +* @param btf BTF object to free +* @return void +*/ LIBBPF_API void btf__free(struct btf *btf); +/** +* @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 length of raw bytes +* @return new instance of BTF object which has to be eventually freed +* with **btf__free()** +*/ LIBBPF_API struct btf *btf__new(const void *data, __u32 size); + +/** +* @brief **btf__new_split()** create a new instance of a BTF object from +* the provided raw data bytes. It takes another BTF instance, **base_btf**, +* which serves as a base BTF, which is extended by types in a newly created +* BTF instance. +* @param data raw bytes +* @param size length of raw bytes +* @param base_btf the base btf object +* @return struct btf * +*/ LIBBPF_API struct btf *btf__new_split(const void *data, __u32 size, struct btf *base_btf); + +/** +* @brief **btf__new_empty()** creates an unpopulated BTF object. +* @return struct btf * +*/ LIBBPF_API struct btf *btf__new_empty(void); + +/** +* @brief **btf__new_empty_split()** creates an unpopulated +* BTF object from an ELF BTF section except with a base BTF +* on top of which split BTF should be based. +* @return struct btf * +*/ LIBBPF_API struct btf *btf__new_empty_split(struct btf *base_btf); LIBBPF_API struct btf *btf__parse(const char *path, struct btf_ext **btf_ext);
Signature · 1 line
2.31.1
Quoted 17 lines · grantseltzer
From: Grant Seltzer <[email protected]>
This adds comments above five functions in
btf.hwhich document their uses. These comments are of a format that doxygen and sphinx can pick up and render. These are rendered by libbpf.readthedocs.orgSigned-off-by Grant Seltzer <[email protected]>--- tools/lib/bpf/btf.h | 37 +++++++++++++++++++++++++++++++++++++ 1 file changed, 37 insertions(+)tools/lib/bpf/btf.h +0
-0
tools/lib/bpf/btf.h line 3
Quoted 3 lines
tools/lib/bpf/btf.h +1
-0@@ -1,5 +1,6 @@/* SPDX-License-Identifier: (LGPL-2.1 OR BSD-2-Clause) */ /* Copyright (c) 2018 Facebook */ +/*! \file */
What's the purpose of this? Is it some sort of description for the entire file?
tools/lib/bpf/btf.h enum btf_endianness { · line 37
Quoted 11 lines
tools/lib/bpf/btf.h +4
-0#ifndef __LIBBPF_BTF_H#define __LIBBPF_BTF_H@@ -30,11 +31,47 @@ enum btf_endianness { BTF_BIG_ENDIAN = 1, }; +/** +* @brief **btf__free()** frees all data of a BTF object. +* @param btf BTF object to free +* @return void
agreed to drop this one
tools/lib/bpf/btf.h enum btf_endianness { · line 45
Quoted 8 lines
tools/lib/bpf/btf.h +6
-0+*/ LIBBPF_API void btf__free(struct btf *btf); +/** +* @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 length of raw bytes
reads a bit weird, bytes don't have "length". "Number of bytes passed in data"?
Quoted 4 lines
tools/lib/bpf/btf.h +3
-0+* @return new instance of BTF object which has to be eventually freed +* with **btf__free()** +*/ LIBBPF_API struct btf *btf__new(const void *data, __u32 size);
tools/lib/bpf/btf.h enum btf_endianness { · line 59
Quoted 10 lines
tools/lib/bpf/btf.h +10
-0+ +/** +* @brief **btf__new_split()** create a new instance of a BTF object from +* the provided raw data bytes. It takes another BTF instance, **base_btf**, +* which serves as a base BTF, which is extended by types in a newly created +* BTF instance. +* @param data raw bytes +* @param size length of raw bytes +* @param base_btf the base btf object +* @return struct btf *
I didn't think I had to leave a suggestion under every such empty @return...
BTW, return documentation is finally a good place where we should document quirky libbpf error returning behavior. Something like this:
``` 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. ```
We should have this remark under every pointer-returning API which has this error-code-as-ptr logic (not all APIs do).
tools/lib/bpf/btf.h enum btf_endianness { · line 64
Quoted 5 lines
tools/lib/bpf/btf.h +4
-0+*/ LIBBPF_API struct btf *btf__new_split(const void *data, __u32 size, struct btf *base_btf); + +/** +* @brief **btf__new_empty()** creates an unpopulated BTF object.
We can add "Use btf__add_*() to populate such BTF object.
tools/lib/bpf/btf.h enum btf_endianness { · line 65
Quoted 1 line
tools/lib/bpf/btf.h +1
-0+* @return struct btf *
another not described @return
tools/lib/bpf/btf.h enum btf_endianness { · line 72
Quoted 7 lines
tools/lib/bpf/btf.h +6
-0+*/ LIBBPF_API struct btf *btf__new_empty(void); + +/** +* @brief **btf__new_empty_split()** creates an unpopulated +* BTF object from an ELF BTF section except with a base BTF +* on top of which split BTF should be based.
If *base_btf* is NULL, btf__new_empty_split() is equivalent to btf__new_empty() and creates non-split BTF.
tools/lib/bpf/btf.h enum btf_endianness { · line 73
Quoted 1 line
tools/lib/bpf/btf.h +1
-0+* @return struct btf *
and one more
Quoted 7 lines
tools/lib/bpf/btf.h +1
-1+*/ LIBBPF_API struct btf *btf__new_empty_split(struct btf *base_btf); LIBBPF_API struct btf *btf__parse(const char *path, struct btf_ext **btf_ext); --2.31.1
Quoted 14 lines · Andrii Nakryiko
Quoted 12 lines · grantseltzer
From: Grant Seltzer <[email protected]>
This adds comments above five functions in
btf.hwhich document their uses. These comments are of a format that doxygen and sphinx can pick up and render. These are rendered by libbpf.readthedocs.orgSigned-off-by Grant Seltzer <[email protected]>--- tools/lib/bpf/btf.h | 37 +++++++++++++++++++++++++++++++++++++ 1 file changed, 37 insertions(+)
Quoted 10 lines
tools/lib/bpf/btf.h line 3
Quoted 8 lines
tools/lib/bpf/btf.h +1
-0@@ -1,5 +1,6 @@/* SPDX-License-Identifier: (LGPL-2.1 OR BSD-2-Clause) */ /* Copyright (c) 2018 Facebook */ +/*! \file */ What's the purpose of this? Is it some sort of description for the entire file?
Correct, we need to explicitly add the file to be tracked by doxygen in order for function links to work.
Quoted 93 lines
tools/lib/bpf/btf.h enum btf_endianness { · line 37
Quoted 12 lines
tools/lib/bpf/btf.h +4
-0#ifndef __LIBBPF_BTF_H#define __LIBBPF_BTF_H@@ -30,11 +31,47 @@ enum btf_endianness { BTF_BIG_ENDIAN = 1, }; +/** +* @brief **btf__free()** frees all data of a BTF object. +* @param btf BTF object to free +* @return void agreed to drop this one
tools/lib/bpf/btf.h enum btf_endianness { · line 45
Quoted 8 lines
tools/lib/bpf/btf.h +6
-0+*/ LIBBPF_API void btf__free(struct btf *btf); +/** +* @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 length of raw bytes reads a bit weird, bytes don't have "length". "Number of bytes passed in
data"?Quoted 4 lines
tools/lib/bpf/btf.h +3
-0+* @return new instance of BTF object which has to be eventually freed +* with **btf__free()** +*/ LIBBPF_API struct btf *btf__new(const void *data, __u32 size);tools/lib/bpf/btf.h enum btf_endianness { · line 59
Quoted 10 lines
tools/lib/bpf/btf.h +10
-0+ +/** +* @brief **btf__new_split()** create a new instance of a BTF object from +* the provided raw data bytes. It takes another BTF instance, **base_btf**, +* which serves as a base BTF, which is extended by types in a newly created +* BTF instance. +* @param data raw bytes +* @param size length of raw bytes +* @param base_btf the base btf object +* @return struct btf * I didn't think I had to leave a suggestion under every such empty @return...
BTW, return documentation is finally a good place where we should document quirky libbpf error returning behavior. Something like this:
``` 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. ```We should have this remark under every pointer-returning API which has this error-code-as-ptr logic (not all APIs do).
tools/lib/bpf/btf.h enum btf_endianness { · line 64
Quoted 5 lines
tools/lib/bpf/btf.h +4
-0+*/ LIBBPF_API struct btf *btf__new_split(const void *data, __u32 size, struct btf *base_btf); + +/** +* @brief **btf__new_empty()** creates an unpopulated BTF object. We can add "Use
btf__add_*()to populate such BTF object.tools/lib/bpf/btf.h enum btf_endianness { · line 65
Quoted 1 line
tools/lib/bpf/btf.h +1
-0+* @return struct btf * another not described @return
tools/lib/bpf/btf.h enum btf_endianness { · line 72
Quoted 7 lines
tools/lib/bpf/btf.h +6
-0+*/ LIBBPF_API struct btf *btf__new_empty(void); + +/** +* @brief **btf__new_empty_split()** creates an unpopulated +* BTF object from an ELF BTF section except with a base BTF +* on top of which split BTF should be based. If *base_btf* is NULL,
btf__new_empty_split()is equivalent tobtf__new_empty()and creates non-split BTF.tools/lib/bpf/btf.h enum btf_endianness { · line 73
Quoted 1 line
tools/lib/bpf/btf.h +1
-0+* @return struct btf * and one more
Quoted 7 lines
tools/lib/bpf/btf.h +1
-1+*/ LIBBPF_API struct btf *btf__new_empty_split(struct btf *base_btf); LIBBPF_API struct btf *btf__parse(const char *path, struct btf_ext **btf_ext); --2.31.1