[GRASS-git] [OSGeo/grass] 56109d: docs: Fix Doxygen warnings due to invalid docstrin...

Thu Jul 24 14:17:14 PDT 2025

  Branch: refs/heads/main
  Home:   https://github.com/OSGeo/grass
  Commit: 56109d36f52c71bbd4404417af9f6e0a95b956de
      https://github.com/OSGeo/grass/commit/56109d36f52c71bbd4404417af9f6e0a95b956de
  Author: Edouard Choinière <27212526+echoix at users.noreply.github.com>
  Date:   2025-07-24 (Thu, 24 Jul 2025)

  Changed paths:
    M grasslib.dox
    M imagery/i.group/main.c
    M include/Make/Doxyfile_arch_html.in
    M include/Make/Doxyfile_arch_latex.in
    M include/grass/dbmi.h
    M include/grass/ogsf.h
    M include/grass/vect/dig_defines.h
    M include/grass/vect/dig_externs.h
    M include/grass/vect/dig_macros.h
    M include/grass/vect/dig_structs.h
    M lib/datetime/type.c
    M lib/db/dbmi_base/table.c
    M lib/db/dbmi_client/c_list_idx.c
    M lib/db/dbmi_client/copy_tab.c
    M lib/display/r_raster.c
    M lib/display/raster2.c
    M lib/display/setup.c
    M lib/display/tran_colr.c
    M lib/gis/asprintf.c
    M lib/gis/basename.c
    M lib/gis/file_name.c
    M lib/gis/find_file.c
    M lib/gis/lrand48.c
    M lib/gis/lz4.h
    M lib/gis/nme_in_mps.c
    M lib/gis/open_misc.c
    M lib/gis/parser.c
    M lib/gis/paths.c
    M lib/gis/rd_cellhd.c
    M lib/gis/tempfile.c
    M lib/gis/wind_format.c
    M lib/gis/wind_scan.c
    M lib/gmath/fft.c
    M lib/gmath/la.c
    M lib/gmath/rand1.c
    M lib/imagery/find.c
    M lib/imagery/list_gp.c
    M lib/imagery/manage_signatures.c
    M lib/imagery/sig.c
    M lib/imagery/sigset.c
    M lib/nviz/cplanes_obj.c
    M lib/ogsf/gp.c
    M lib/ogsf/gs.c
    M lib/ogsf/gs2.c
    M lib/ogsf/gsd_objs.c
    M lib/ogsf/gsd_views.c
    M lib/ogsf/gsdrape.c
    M lib/proj/convert.c
    M lib/raster/mask_info.c
    M lib/raster3d/headerinfo.c
    M lib/raster3d/mask.c
    M lib/raster3d/open.c
    M lib/raster3d/open2.c
    M lib/raster3d/resample.c
    M lib/raster3d/windowio.c
    M lib/vector/Vlib/area.c
    M lib/vector/Vlib/cats.c
    M lib/vector/Vlib/close.c
    M lib/vector/Vlib/intersect.c
    M lib/vector/Vlib/intersect2.c
    M lib/vector/Vlib/level_two.c
    M lib/vector/Vlib/net_analyze.c
    M lib/vector/Vlib/open.c
    M lib/vector/Vlib/read_nat.c
    M lib/vector/Vlib/simple_features.c
    M lib/vector/neta/timetables.c
    M lib/vector/vedit/zbulk.c

  Log Message:
  -----------
  docs: Fix Doxygen warnings due to invalid docstring syntax or missing tags (#6097)

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 https://github.com/OSGeo/grass/pull/5191 and https://github.com/OSGeo/grass/pull/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 yet.

* docs(lib): Update parameter descriptions for to match function signature

* docs(lib): Fix formatting of parameter descriptions to solve doxygen warnings

* man: Ignore cmake folders in doxygen config file

* docs(lib): Update parameter descriptions to match function signature

* lib/display/tran_colr: Fill docs for D_color_number_to_RGB according to signature

* lib/display/raster2 Update parameter descriptions to match function signature

* include: Update file paths in header comments to include 'grass' directory

* docs: Escape `@`, `<` or `>` in doxygen docstrings

* docs: Add missing param tags in doxygen docstrings

* docs: Rename param tags to match signature in doxygen docstrings

* docs: Escape `/*` to avoid nested comment warning in grasslib.dox

* docs: Fix misformed `<b>` tag in doxygen docstrings of lib/gmath/fft.c

* docs(lib): Fix formatting of parameter descriptions to solve doxygen warnings

* docs: Document parameters and returns in doxygen docstrings

* docs(lib): Fix formatting of lz4.h

* docs: Fix typo in file name of lib/imagery/manage_signatures.c header

* docs: Add missing param tags in doxygen docstrings

* docs: Rename param tags to match signature in doxygen docstrings

* docs(lib): Fix formatting of parameter descriptions to solve doxygen warnings

* Apply suggestions from code review

Co-authored-by: Anna Petrasova <kratochanna at gmail.com>

* Apply suggestions from code review

---------

Co-authored-by: Anna Petrasova <kratochanna at gmail.com>

To unsubscribe from these emails, change your notification settings at https://github.com/OSGeo/grass/settings/notifications