JordanYates commented 1 month ago

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). https://github.com/zephyrproject-rtos/zephyr/blob/be682e22e166c33a67c1db0755f8ca20c37b6576/include/zephyr/net/capture.h#L274-L285

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 commented 1 month ago

CC @carlescufi @fabiobaltieri @stephanosio

aescolar commented 1 month ago

@JordanYates what doxygen version are you using?

kartben commented 1 month ago

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 commented 1 month ago

@JordanYates what doxygen version are you using?

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

JordanYates commented 1 month ago

More examples of PRs that introduce warnings:

72483

31583

kartben commented 3 weeks ago

The documentation build workflow in CI is not detecting problems with doxygen comments.

This is a regression introduced with https://github.com/zephyrproject-rtos/zephyr/commit/2c89bf57983782593dedc0f34f105fcde735677f#diff-1048a3f83dfee0a99ce3c07fede976bbd6a6b65f8bdae55ada11e6a1dda452c7L88

Independently from this, the doxygen docs for capture.h seems bogus as it has nested INTERNAL_HIDDEN sections ?

zephyrproject-rtos / zephyr

ci: doxygen build warning not being detected by CI #72605

72483

31583