docs: Fix Doxygen warnings due to invalid docstring syntax or missing tags

[echoix]

Similar to the bunch of fixes I did with sphinx in the last months or so, here is a first PR solving Doxygen warnings that can now be seen in CI (since #6092).

It is a first batch with what I have yet, no particular grouping expect at the commit level.

• Make doxygen ignore CMake build folders when looking for source documents, like in config: Adjust gitignore for CMake #5191 and chore: Update .gitignore for cmake in Visual Studio #5208
• Fix wrong parameter names in docstrings
• Add non documented parameters to the docstrings
  • Feel free to suggest some content when they didn’t exist yet, I went the easiest way that wasn’t creating something misleading. So when I didn’t know, I didn’t describe it at all.
• fix syntax, and escape some characters when complaining
• A small number of files I had to reflow the docstrings to be readable again, as it was joined together probably by a clang-format once. So these have a bigger diff.

There’s still lots of the same categories, it’s only what I had done yesterday.

[echoix]

Locally, I was redirecting the console output into two separate files for stdout and stderr, as all the warnings and problems to fix are found in the stderr. And the output had more lines than my scroll buffer

I was using something like

make -j1 htmldocs > >(tee -a doxygen_htmldocs.stdout.5.log) 2> >(tee -a doxygen_htmldocs.stderr.5.log >&2)

[nilason]

Clang (at least) have the -Wdocumentation configuration flag to spot errors, e.g.:

/opt/local/bin/clang-mp-20 -I/opt/local/include -isystem/opt/local/include -isystem/opt/local/include/libomp -std=c11 -I/opt/local/include -isysroot/Library/Developer/CommandLineTools/SDKs/MacOSX15.sdk -arch arm64 -O1 --debug -Wall -Wextra -Wpedantic -Wvla -Wdocumentation  -DGL_SILENCE_DEPRECATION  -fno-common  -I/User/dev/grass/dist.aarch64-apple-darwin23.6.0/include -I/User/dev/grass/dist.aarch64-apple-darwin23.6.0/include   -fopenmp -DGRASS_VERSION_DATE=\"'2025'\" -DPACKAGE=\""grasslibs"\"   -I/opt/local/include -I/opt/local/include   -I/opt/local/include/libomp -I/User/dev/grass/dist.aarch64-apple-darwin23.6.0/include -I/User/dev/grass/dist.aarch64-apple-darwin23.6.0/include -DRELDIR=\"lib/gis\" -o OBJ.aarch64-apple-darwin23.6.0/area_sphere.o -c area_sphere.c
area_sphere.c:64:15: warning: empty paragraph passed to '\param' command [-Wdocumentation]
   64 |  * \param north
      |    ~~~~~~~~~~~^
   65 |  * \param[in] south
      |  ~
area_sphere.c:65:19: warning: empty paragraph passed to '\param' command [-Wdocumentation]
   65 |  * \param[in] south
      |    ~~~~~~~~~~~~~~~^
   66 |  * \return double
      |  ~
2 warnings generated.

...

/opt/local/bin/clang-mp-20 -I/opt/local/include -isystem/opt/local/include -isystem/opt/local/include/libomp -std=c11 -I/opt/local/include -isysroot/Library/Developer/CommandLineTools/SDKs/MacOSX15.sdk -arch arm64 -O1 --debug -Wall -Wextra -Wpedantic -Wvla -Wdocumentation  -DGL_SILENCE_DEPRECATION  -fno-common  -I/User/dev/grass/dist.aarch64-apple-darwin23.6.0/include -I/User/dev/grass/dist.aarch64-apple-darwin23.6.0/include   -fopenmp -DGRASS_VERSION_DATE=\"'2025'\" -DPACKAGE=\""grasslibs"\"   -I/opt/local/include -I/opt/local/include   -I/opt/local/include/libomp -I/User/dev/grass/dist.aarch64-apple-darwin23.6.0/include -I/User/dev/grass/dist.aarch64-apple-darwin23.6.0/include -DRELDIR=\"lib/gis\" -o OBJ.aarch64-apple-darwin23.6.0/paths.o -c paths.c
paths.c:123:11: warning: parameter 'stat' not found in the function declaration [-Wdocumentation]
  123 |  * \param stat pointer to structure filled with file information
      |           ^~~~
paths.c:123:11: note: did you mean 'buf'?
  123 |  * \param stat pointer to structure filled with file information
      |           ^~~~
      |           buf
paths.c:140:11: warning: parameter 'stat' not found in the function declaration [-Wdocumentation]
  140 |  * \param stat pointer to structure filled with file information
      |           ^~~~
paths.c:140:11: note: did you mean 'buf'?
  140 |  * \param stat pointer to structure filled with file information
      |           ^~~~
      |           buf
2 warnings generated.

I used it extensively a few years ago fixing GEOS docs.

[echoix]

Clang (at least) have the -Wdocumentation configuration flag to spot errors, e.g.:

/opt/local/bin/clang-mp-20 -I/opt/local/include -isystem/opt/local/include -isystem/opt/local/include/libomp -std=c11 -I/opt/local/include -isysroot/Library/Developer/CommandLineTools/SDKs/MacOSX15.sdk -arch arm64 -O1 --debug -Wall -Wextra -Wpedantic -Wvla -Wdocumentation  -DGL_SILENCE_DEPRECATION  -fno-common  -I/User/dev/grass/dist.aarch64-apple-darwin23.6.0/include -I/User/dev/grass/dist.aarch64-apple-darwin23.6.0/include   -fopenmp -DGRASS_VERSION_DATE=\"'2025'\" -DPACKAGE=\""grasslibs"\"   -I/opt/local/include -I/opt/local/include   -I/opt/local/include/libomp -I/User/dev/grass/dist.aarch64-apple-darwin23.6.0/include -I/User/dev/grass/dist.aarch64-apple-darwin23.6.0/include -DRELDIR=\"lib/gis\" -o OBJ.aarch64-apple-darwin23.6.0/area_sphere.o -c area_sphere.c
area_sphere.c:64:15: warning: empty paragraph passed to '\param' command [-Wdocumentation]
   64 |  * \param north
      |    ~~~~~~~~~~~^
   65 |  * \param[in] south
      |  ~
area_sphere.c:65:19: warning: empty paragraph passed to '\param' command [-Wdocumentation]
   65 |  * \param[in] south
      |    ~~~~~~~~~~~~~~~^
   66 |  * \return double
      |  ~
2 warnings generated.

...

/opt/local/bin/clang-mp-20 -I/opt/local/include -isystem/opt/local/include -isystem/opt/local/include/libomp -std=c11 -I/opt/local/include -isysroot/Library/Developer/CommandLineTools/SDKs/MacOSX15.sdk -arch arm64 -O1 --debug -Wall -Wextra -Wpedantic -Wvla -Wdocumentation  -DGL_SILENCE_DEPRECATION  -fno-common  -I/User/dev/grass/dist.aarch64-apple-darwin23.6.0/include -I/User/dev/grass/dist.aarch64-apple-darwin23.6.0/include   -fopenmp -DGRASS_VERSION_DATE=\"'2025'\" -DPACKAGE=\""grasslibs"\"   -I/opt/local/include -I/opt/local/include   -I/opt/local/include/libomp -I/User/dev/grass/dist.aarch64-apple-darwin23.6.0/include -I/User/dev/grass/dist.aarch64-apple-darwin23.6.0/include -DRELDIR=\"lib/gis\" -o OBJ.aarch64-apple-darwin23.6.0/paths.o -c paths.c
paths.c:123:11: warning: parameter 'stat' not found in the function declaration [-Wdocumentation]
  123 |  * \param stat pointer to structure filled with file information
      |           ^~~~
paths.c:123:11: note: did you mean 'buf'?
  123 |  * \param stat pointer to structure filled with file information
      |           ^~~~
      |           buf
paths.c:140:11: warning: parameter 'stat' not found in the function declaration [-Wdocumentation]
  140 |  * \param stat pointer to structure filled with file information
      |           ^~~~
paths.c:140:11: note: did you mean 'buf'?
  140 |  * \param stat pointer to structure filled with file information
      |           ^~~~
      |           buf
2 warnings generated.

I used it extensively a few years ago fixing GEOS docs.

Interesting! I’ll for sure try it out, but at least Doxygen, even on the older version, is still able to spot a lot. And with VS code, since it is a full path+line number+column number, I can just CTRL+click and get directly to the place to fix. I didn’t have that much luck with a compiler output yet, as we usually use relative commands from makefiles