Skip to contentSkip to conversation

libbpf: Add API documentation convention guidelines

PATCH In review grantseltzer 3 participants 4 messages Oct 4, 2021 – Oct 7, 2021

Subsystems (2)
lore
Share & tools
lore
#0 lore raw

PATCH 1/1 libbpf: Add API documentation convention guidelines

From: Grant Seltzer <[email protected]>

This adds a section to the documentation for libbpf naming convention which describes how to document API features in libbpf, specifically the format of which API doc comments need to conform to.

---
 .../bpf/libbpf/libbpf_naming_convention.rst   | 40 +++++++++++++++++++
 1 file changed, 40 insertions(+)
Documentation/bpf/libbpf/libbpf_naming_convention.rst +40 -0
index 9c68d5014ff1..5f42f172987a 100644
@@ -150,6 +150,46 @@ mirror of the mainline's version of libbpf for a stand-alone build.
 However, all changes to libbpf's code base must be upstreamed through
 the mainline kernel tree.
 
+
+API documentation convention
+============================
+
+The libbpf API is documented via comments above definitions in
+header files. These comments can be rendered by doxygen and sphinx
+for well organized html output. This section describes the
+convention in which these comments should be formated.
+
+Here is an example from btf.h:
+
+.. code-block:: c
+
+        /**
+        * @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 number of bytes passed in `data`
+        * @return new BTF object instance which has to be eventually freed with
+        * **btf__free()**
+        *
+        * 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.
+        */
+
+The comment must start with a block comment of the form '/**'.
+
+The documentation always starts with a @brief directive. This line is a short
+description about this API. It starts with the name of the API, denoted in bold
+like so: **api_name**. Please include an open and close parenthesis if this is a
+function. Follow with the short description of the API. A longer form description
+can be added below the last directive, at the bottom of the comment.
+
+Parameters are denoted with the @param directive, there should be one for each
+parameter. If this is a function with a non-void return, use the @return directive
+to document it.
+
 License
 -------------------
 
Signature · 1 line
2.31.1
reviewer Acked-by on v1 1/1
#1 lore raw
Quoted 9 lines · grantseltzer

From: Grant Seltzer <[email protected]>

This adds a section to the documentation for libbpf naming convention which describes how to document API features in libbpf, specifically the format of which API doc comments need to conform to.

Quoted 58 lines
---
 .../bpf/libbpf/libbpf_naming_convention.rst   | 40 +++++++++++++++++++
 1 file changed, 40 insertions(+)
Documentation/bpf/libbpf/libbpf_naming_convention.rst +40 -1
index 9c68d5014ff1..5f42f172987a 100644
@@ -150,6 +150,46 @@ mirror of the mainline's version of libbpf for a stand-alone build.
 However, all changes to libbpf's code base must be upstreamed through
 the mainline kernel tree.
 
+
+API documentation convention
+============================
+
+The libbpf API is documented via comments above definitions in
+header files. These comments can be rendered by doxygen and sphinx
+for well organized html output. This section describes the
+convention in which these comments should be formated.
+
+Here is an example from btf.h:
+
+.. code-block:: c
+
+        /**
+        * @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 number of bytes passed in `data`
+        * @return new BTF object instance which has to be eventually freed with
+        * **btf__free()**
+        *
+        * 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.
+        */
+
+The comment must start with a block comment of the form '/**'.
+
+The documentation always starts with a @brief directive. This line is a short
+description about this API. It starts with the name of the API, denoted in bold
+like so: **api_name**. Please include an open and close parenthesis if this is a
+function. Follow with the short description of the API. A longer form description
+can be added below the last directive, at the bottom of the comment.
+
+Parameters are denoted with the @param directive, there should be one for each
+parameter. If this is a function with a non-void return, use the @return directive
+to document it.
+
 License
 -------------------
 
--

2.31.1

#2 lore raw
Quoted 5 lines · Song Liu
Quoted 3 lines · grantseltzer

From: Grant Seltzer <[email protected]>

Quoted 9 lines
Quoted 6 lines

This adds a section to the documentation for libbpf naming convention which describes how to document API features in libbpf, specifically the format of which API doc comments need to conform to.

Applied to bpf-next, thanks. I've fixed the example block comment indentation (it was off by one space for all but the first line). I also noticed that vim syntax highlighting were treating '/**' as something special, so I added escaping: '/\*\*', but it's not easy for me to serve html from my dev server, so not sure if that renders ok. At least make htmldocs didn't complain.

BTW, as we'll have (hopefully) more contributions to libbpf docs, it would be nice to integrate make htmldocs "check" into selftests/bpf's Makefile. Can you please see if that's possible? Ideally we'd only build docs inside Documentation/bpf to speed things up. Seems like we currently have one error/warning there, so we are in a pretty good shape already, but playing a proactive defense here seems like a prudent approach?

Quoted 58 lines
Quoted 58 lines
---
 .../bpf/libbpf/libbpf_naming_convention.rst   | 40 +++++++++++++++++++
 1 file changed, 40 insertions(+)
Documentation/bpf/libbpf/libbpf_naming_convention.rst +40 -1
index 9c68d5014ff1..5f42f172987a 100644
@@ -150,6 +150,46 @@ mirror of the mainline's version of libbpf for a stand-alone build.
 However, all changes to libbpf's code base must be upstreamed through
 the mainline kernel tree.
 
+
+API documentation convention
+============================
+
+The libbpf API is documented via comments above definitions in
+header files. These comments can be rendered by doxygen and sphinx
+for well organized html output. This section describes the
+convention in which these comments should be formated.
+
+Here is an example from btf.h:
+
+.. code-block:: c
+
+        /**
+        * @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 number of bytes passed in `data`
+        * @return new BTF object instance which has to be eventually freed with
+        * **btf__free()**
+        *
+        * 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.
+        */
+
+The comment must start with a block comment of the form '/**'.
+
+The documentation always starts with a @brief directive. This line is a short
+description about this API. It starts with the name of the API, denoted in bold
+like so: **api_name**. Please include an open and close parenthesis if this is a
+function. Follow with the short description of the API. A longer form description
+can be added below the last directive, at the bottom of the comment.
+
+Parameters are denoted with the @param directive, there should be one for each
+parameter. If this is a function with a non-void return, use the @return directive
+to document it.
+
 License
 -------------------
 
--

2.31.1

#3 lore raw
Quoted 24 lines · Andrii Nakryiko
Quoted 5 lines · Song Liu
Quoted 3 lines · grantseltzer

From: Grant Seltzer <[email protected]>

Quoted 9 lines
Quoted 6 lines

This adds a section to the documentation for libbpf naming convention which describes how to document API features in libbpf, specifically the format of which API doc comments need to conform to.

Applied to bpf-next, thanks. I've fixed the example block comment indentation (it was off by one space for all but the first line). I also noticed that vim syntax highlighting were treating '/**' as something special, so I added escaping: '/\*\*', but it's not easy for me to serve html from my dev server, so not sure if that renders ok. At least make htmldocs didn't complain.

Quoted 7 lines

BTW, as we'll have (hopefully) more contributions to libbpf docs, it would be nice to integrate make htmldocs "check" into selftests/bpf's Makefile. Can you please see if that's possible? Ideally we'd only build docs inside Documentation/bpf to speed things up. Seems like we currently have one error/warning there, so we are in a pretty good shape already, but playing a proactive defense here seems like a prudent approach?

That's a good idea, I will work on this.

Quoted 60 lines
Quoted 60 lines
Quoted 60 lines

---
 .../bpf/libbpf/libbpf_naming_convention.rst   | 40 +++++++++++++++++++
 1 file changed, 40 insertions(+)
Documentation/bpf/libbpf/libbpf_naming_convention.rst +40 -1
index 9c68d5014ff1..5f42f172987a 100644
@@ -150,6 +150,46 @@ mirror of the mainline's version of libbpf for a stand-alone build.
 However, all changes to libbpf's code base must be upstreamed through
 the mainline kernel tree.
 
+
+API documentation convention
+============================
+
+The libbpf API is documented via comments above definitions in
+header files. These comments can be rendered by doxygen and sphinx
+for well organized html output. This section describes the
+convention in which these comments should be formated.
+
+Here is an example from btf.h:
+
+.. code-block:: c
+
+        /**
+        * @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 number of bytes passed in `data`
+        * @return new BTF object instance which has to be eventually freed with
+        * **btf__free()**
+        *
+        * 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.
+        */
+
+The comment must start with a block comment of the form '/**'.
+
+The documentation always starts with a @brief directive. This line is a short
+description about this API. It starts with the name of the API, denoted in bold
+like so: **api_name**. Please include an open and close parenthesis if this is a
+function. Follow with the short description of the API. A longer form description
+can be added below the last directive, at the bottom of the comment.
+
+Parameters are denoted with the @param directive, there should be one for each
+parameter. If this is a function with a non-void return, use the @return directive
+to document it.
+
 License
 -------------------
 
--

2.31.1