Skip to contentSkip to conversation

Add sphinx code documentation comments

PATCH Superseded grantseltzer 2 participants 3 messages Sep 14, 2021 – Sep 15, 2021

Subsystems (2)

v2 of 3 Superseded Latest is v3 →

lore
Share & tools
lore
#0 lore raw

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
index 4a711f990904..05e06f0136e3 100644
@@ -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
#1 lore raw
Quoted 17 lines · grantseltzer

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 +0 -0
index 4a711f990904..05e06f0136e3 100644

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

#2 lore raw
Quoted 14 lines · Andrii Nakryiko
Quoted 12 lines · grantseltzer

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(+)
Quoted 10 lines

tools/lib/bpf/btf.h line 3

Quoted 8 lines
tools/lib/bpf/btf.h +1 -0
index 4a711f990904..05e06f0136e3 100644
@@ -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 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