From 8b1010fb7ab1a3833cef0e2788e1aa7cb239d85b Mon Sep 17 00:00:00 2001 From: Quentin Deslandes Date: Wed, 6 Nov 2024 21:34:53 +0100 Subject: [PATCH 1/4] doc: add dependency from the Doxygen target to the Doxygen config file Add $BUILD/doc/Doxyfile (the Doxygen config file override created from doc/Doxyfile.in) as a dependency of the Doxygen XML generation. This change will ensure Doxygen is run again if its configuration has changed. --- doc/CMakeLists.txt | 1 + 1 file changed, 1 insertion(+) diff --git a/doc/CMakeLists.txt b/doc/CMakeLists.txt index b6b6a62..5014189 100644 --- a/doc/CMakeLists.txt +++ b/doc/CMakeLists.txt @@ -72,6 +72,7 @@ add_custom_command( add_custom_command( COMMAND Doxygen::doxygen ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile DEPENDS + ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile.base ${bf_srcs} OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/xml/index.xml From 68861e564edba2b0f007ad165ab30df29feb0bfb Mon Sep 17 00:00:00 2001 From: Quentin Deslandes Date: Wed, 6 Nov 2024 21:36:34 +0100 Subject: [PATCH 2/4] doc: always build the doc without cache Sphinx uses a cache to make the generation faster. However, if a change is made to the source code documentation (e.g. in a comment), Sphinx won't detect it and won't rebuild the documentation. Prevent Sphinx from using its cache to prevent out-of-date documentation. --- doc/CMakeLists.txt | 1 + 1 file changed, 1 insertion(+) diff --git a/doc/CMakeLists.txt b/doc/CMakeLists.txt index 5014189..d781fea 100644 --- a/doc/CMakeLists.txt +++ b/doc/CMakeLists.txt @@ -92,6 +92,7 @@ add_custom_command( ${CMAKE_CURRENT_BINARY_DIR}/_templates COMMAND ${SPHINX_BIN} + -E # Ensure the Doxygen changes are accounted for -W # Return non-zero if a warning is triggered... --keep-going # ... but don't stop as soon as there is a warning. -q # Quiet. From 54e28fc0a44d62cdac7305123de2035ec6806deb Mon Sep 17 00:00:00 2001 From: Quentin Deslandes Date: Wed, 6 Nov 2024 21:38:34 +0100 Subject: [PATCH 3/4] doc: enable Doxygen autolink support Breathe doesn't recognize Doxygen's `@ref` annotations, meaning every `@ref` symbol is ignored and no hyperlink is created in the documentation. Instead, enable Doxygen's autolink feature so `symbol()` can be used to link to a symbol in the documentation. --- doc/Doxyfile.in | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/Doxyfile.in b/doc/Doxyfile.in index ecda5a3..bbca5ce 100644 --- a/doc/Doxyfile.in +++ b/doc/Doxyfile.in @@ -5,7 +5,7 @@ OUTPUT_DIRECTORY = "@CMAKE_CURRENT_BINARY_DIR@" STRIP_FROM_PATH = "@CMAKE_SOURCE_DIR@/src" STRIP_FROM_INC_PATH = "@CMAKE_SOURCE_DIR@/src" OPTIMIZE_OUTPUT_FOR_C = YES -AUTOLINK_SUPPORT = NO +AUTOLINK_SUPPORT = YES IDL_PROPERTY_SUPPORT = NO NUM_PROC_THREADS = 0 From bdae6fedcb9a6a0a93ae055db79151b7884e49b6 Mon Sep 17 00:00:00 2001 From: Quentin Deslandes Date: Thu, 7 Nov 2024 07:34:07 +0100 Subject: [PATCH 4/4] doc: clarify how Doxygen comments should be written Modify the Doxygen comments guidelines to ensure references to functions are properly processed by Breathe: use ` (backticks) instead of @ref or @c and end functions with parentheses. --- doc/developers/style.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/developers/style.rst b/doc/developers/style.rst index c6e60c7..82b3f72 100644 --- a/doc/developers/style.rst +++ b/doc/developers/style.rst @@ -43,10 +43,10 @@ Regarding Doxygen usage: - For the sake of clarity, a function's multi-lines documentation should have the first and last comment line empty. This is specific to Doxygen comments, for all other use cases, the rule above still stands. - The first line of a function's documentation should be a brief explanation of its purpose, but ``@brief`` should not be used: ``@brief`` doesn't affect the generated output, avoid using it anywhere to maintain consistency. -- Parameters are tagged with ``@param``. If a parameter's documentation is too long to fit on a single line, indent the next line properly to fit under the parameter's name (see example below). +- Parameters are tagged with ``@param``. If a parameter's documentation is too long to fit on a single line, indent the next line properly to fit under the parameter's name (see example below). You can refer to the function's parameters in its documentation using `@p`. - Return value (if any) is tagged with ``@return``. The same line break rule applies as to ``@param``. - Always use the ``@`` version of the Doxygen directives, not the ``\`` one. -- Use ``@ref`` to refer to other symbols from ``bpfilter`` and ``@p`` to refer to external symbols or parameter names. +- Refer to symbols from the codebase using `\`` (backticks). For functions, use `\`function_name()\`` so Doxygen will automatically create a link to the function definition. - Use ``@code{.c}`` and ``@endcode`` to integrate code example. Remember about this, as it's sometimes clearer to have a simple code example than 20 lines of text. .. code:: c @@ -57,7 +57,7 @@ Regarding Doxygen usage: * The memory allocated by this function for @p ifaces must be freed by the * caller. * - * @param ifaces Array of @ref bf_if_iface structures. The array will be + * @param ifaces Array of `bf_if_iface` structures. The array will be * allocated by the function and the caller is responsible for * freeing it. * @return On success, return the number of interfaces contained in