libbpf: Add API documentation convention guidelines
Subsystems (2)
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
@@ -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
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.
Signed-off-by Grant Seltzer <[email protected]>
Quoted 58 lines
--- .../bpf/libbpf/libbpf_naming_convention.rst | 40 +++++++++++++++++++ 1 file changed, 40 insertions(+)Documentation/bpf/libbpf/libbpf_naming_convention.rst +40
-1@@ -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
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.
Signed-off-by Grant Seltzer <[email protected]>Acked-by Song Liu <[email protected]>
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@@ -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
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.
Signed-off-by Grant Seltzer <[email protected]>Acked-by Song Liu <[email protected]>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 htmldocsdidn'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'sMakefile. Can you please see if that's possible? Ideally we'd only build docs insideDocumentation/bpfto 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@@ -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