Multiple improvements to the documentation generation

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
@@ -91,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.

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
 

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