ci: doxygen build warning not being detected by CI

[JordanYates]

Is your enhancement proposal related to a problem? Please describe.

The documentation build workflow in CI is not detecting problems with doxygen comments.
As an example, the cooked parameter name in the comment does not match the ctx name in the prototype, but passes CI (#70926).

zephyr/include/zephyr/net/capture.h

Lines 274 to 285 in be682e2

	* @param cooked Cooked context struct allocated by user.
	* @param hatype Link-layer address type
	* @param halen Link-layer address length (maximum is 8 bytes)
	* @param addr Link-layer address
	*
	* @return 0 if ok, <0 if context initialization failed
	*/
	#if defined(CONFIG_NET_CAPTURE_COOKED_MODE)
	int net_capture_cooked_setup(struct net_capture_cooked *ctx,
	uint16_t hatype,
	uint16_t halen,
	uint8_t *addr);

As is, this generates doxygen warnings when building the docs normally:

(.zephyr_venv) jordan@TAURUS:~/code/zephyr/zephyr/doc$ make html
cmake \
        -GNinja \
        -B_build \
        -S. \
        -DDOC_TAG=development \
        -DSPHINXOPTS="-j 16 -W --keep-going -T" \
        -DSPHINXOPTS_EXTRA="" \
        -DLATEXMKOPTS="-halt-on-error -no-shell-escape" \
        -DDT_TURBO_MODE=0
Loading Zephyr module(s) (Zephyr base (cached)): doc
-- Cache files will be written to: /home/jordan/.cache/zephyr
-- Found west (found suitable version "1.2.0", minimum required is "1.0.0")
-- Zephyr base: /home/jordan/code/zephyr/zephyr
-- Configuring done
-- Generating done
-- Build files have been written to: /home/jordan/code/zephyr/zephyr/doc/_build
cmake --build _build --target html
[0/2] Generating Devicetree bindings documentation...
[1/2] Running Sphinx HTML build...
Running Sphinx v6.2.1
Building Kconfig database...... done
Preparing Doxyfile...
Checking if Doxygen needs to be run...
Running Doxygen...
WARNING: /home/jordan/code/zephyr/zephyr/include/zephyr/net/capture.h:274: argument 'cooked' of command @param is not found in the argument list of net_capture_cooked_setup(struct net_capture_cooked *ctx, uint16_t hatype, uint16_t halen, uint8_t *addr)

[aescolar]

CC @carlescufi @fabiobaltieri @stephanosio

[aescolar]

@JordanYates what doxygen version are you using?

[kartben]

This actually looks like a bug in the capture.h header file, where some of the INTERNAL_HIDDEN sections might be improperly used (these two @cond INTERNAL_HIDDEN being open consecutively are definitely suspicious, or at least redundant).

See rendered doc at https://docs.zephyrproject.org/latest/doxygen/html/capture_8h.html where many of the API that I think are meant to be public effectively end up not showing up (and hence not generating a warning when building in CI, probably)

https://docs.zephyrproject.org/api-coverage/latest/zephyr/net/capture.h.gcov.html also highlights (or rather, doesn't!) which APIs are "covered" by doxygen

@rlubos @jukkar

[JordanYates]

@JordanYates what doxygen version are you using?

(.zephyr_venv) jordan@TAURUS:~/code/workspace$ doxygen --version
1.9.1

[JordanYates]

More examples of PRs that introduce warnings:
#72483
#31583