Missing `hardware_busctrl` Doxygen group #2035

New issue

Closed

opened 2024-11-12 12:20:35 -06:00 by lurch · 2 comments

lurch commented

2024-11-12 12:20:35 -06:00

(Migrated from github.com)

There's a simple script here which checks that every \ingroup has a matching \defgroup (used with various Doxygen tags).

Most of the errors it reports are red-herrings caused by various CMSIS headers, but two of the errors that it reports look genuine:

src/rp2040/hardware_structs/include/hardware/structs/busctrl.h uses \ingroup hardware_busctrl which was never defined
src/rp2350/hardware_structs/include/hardware/structs/busctrl.h uses \ingroup hardware_busctrl which was never defined

and indeed doing a git grep shows that this group is never defined anywhere:

$ git grep hardware_busctrl
src/rp2040/hardware_structs/include/hardware/structs/busctrl.h: *  \ingroup hardware_busctrl
src/rp2350/hardware_structs/include/hardware/structs/busctrl.h: *  \ingroup hardware_busctrl

These files are both auto-generated, so I'll assign this (very low priority) issue to @matiasilva

I dunno what the "right" fix is here, but perhaps the following results suggests that the easiest solution would be just to get rid of these \ingroup hardware_busctrl lines from these autogenerated headers? 🤷‍♂️

$ git -C src/rp2040/hardware_structs grep "defgroup"
$ git -C src/rp2350/hardware_structs grep "defgroup"
$ git -C src/rp2040/hardware_structs grep "ingroup"
include/hardware/structs/busctrl.h: *  \ingroup hardware_busctrl
include/hardware/structs/clocks.h: *  \ingroup hardware_clocks
include/hardware/structs/clocks.h: *  \ingroup hardware_clocks
include/hardware/structs/io_bank0.h: * \ingroup hardware_gpio
include/hardware/structs/resets.h: *  \ingroup hardware_resets
$ git -C src/rp2350/hardware_structs grep "ingroup"
include/hardware/structs/busctrl.h: *  \ingroup hardware_busctrl
include/hardware/structs/clocks.h: *  \ingroup hardware_clocks
include/hardware/structs/clocks.h: *  \ingroup hardware_clocks
include/hardware/structs/io_bank0.h: * \ingroup hardware_gpio
include/hardware/structs/resets.h: *  \ingroup hardware_resets
include/hardware/structs/ticks.h: *  \ingroup hardware_ticks

There's a simple script [here](https://github.com/raspberrypi/pico-sdk/blob/master/tools/check_doxygen_groups.py) which checks that every `\ingroup` has a matching `\defgroup` (used with various Doxygen tags). Most of the errors it reports are red-herrings caused by various CMSIS headers, but two of the errors that it reports look genuine: ``` src/rp2040/hardware_structs/include/hardware/structs/busctrl.h uses \ingroup hardware_busctrl which was never defined src/rp2350/hardware_structs/include/hardware/structs/busctrl.h uses \ingroup hardware_busctrl which was never defined ``` and indeed doing a `git grep` shows that this group is never defined anywhere: ```console $ git grep hardware_busctrl src/rp2040/hardware_structs/include/hardware/structs/busctrl.h: * \ingroup hardware_busctrl src/rp2350/hardware_structs/include/hardware/structs/busctrl.h: * \ingroup hardware_busctrl ``` These files are both auto-generated, so I'll assign this (very low priority) issue to @matiasilva I dunno what the "right" fix is here, but perhaps the following results suggests that the easiest solution would be just to get rid of these `\ingroup hardware_busctrl` lines from these autogenerated headers? :man_shrugging: ```console $ git -C src/rp2040/hardware_structs grep "defgroup" $ git -C src/rp2350/hardware_structs grep "defgroup" $ git -C src/rp2040/hardware_structs grep "ingroup" include/hardware/structs/busctrl.h: * \ingroup hardware_busctrl include/hardware/structs/clocks.h: * \ingroup hardware_clocks include/hardware/structs/clocks.h: * \ingroup hardware_clocks include/hardware/structs/io_bank0.h: * \ingroup hardware_gpio include/hardware/structs/resets.h: * \ingroup hardware_resets $ git -C src/rp2350/hardware_structs grep "ingroup" include/hardware/structs/busctrl.h: * \ingroup hardware_busctrl include/hardware/structs/clocks.h: * \ingroup hardware_clocks include/hardware/structs/clocks.h: * \ingroup hardware_clocks include/hardware/structs/io_bank0.h: * \ingroup hardware_gpio include/hardware/structs/resets.h: * \ingroup hardware_resets include/hardware/structs/ticks.h: * \ingroup hardware_ticks ```

Rows
Columns

Missing hardware_busctrl Doxygen group #2035

Missing `hardware_busctrl` Doxygen group #2035