Question

I have a program that multiple people write and edit. Some parts of the program link software values to specific pins specified by the user. The pins that are in use, are spread out between multiple files, and I would like to create one central reference. I would like to use doxygen to create a reference that lists the pin number, and then the assigned purpose. All of the pin assignments are defined in header files like so:

//spi1.h
// Pin assignments (GPIO row A)
#define SPI_SS_1            (0)
#define SPI_CLK_1           (1)
#define SPI_MOSI_1          (2)
#define SPI_MISO_1          (3)

//spi2.h
// Pin assignments (GPIO row A)
#define SPI_CLK_2           (7)
#define SPI_DOUT_2          (8)
#define SPI_DIN_2           (9)
#define SPI_CS_2_0          (10)
#define SPI_CS_2_1          (11)
#define SPI_CS_2_2          (12)
#define SPI_CS_2_3          (13)

How would I use doxygen to create a reference chart for these values?

Answer 1

You can group these #defines together using doxygen’s grouping mechanisms. From this page:

To define a group, you should put the \defgroup command in a special comment block. The first argument of the command is a label that should uniquely identify the group. The second argument is the name or title of the group as it should appear in the documentation.

You can make an entity a member of a specific group by putting a \ingroup command inside its documentation block.

To avoid putting \ingroup commands in the documentation for each member you can also group members together by the open marker @{ before the group and the closing marker @} after the group. The markers can be put in the documentation of the group definition or in a separate documentation block.

In practice, you could put in each of your header files something like:

/** \addtogroup pin-assignments
 *  @{
 */
#define SPI_SS_1            (0)
#define SPI_CLK_1           (1)
#define SPI_MOSI_1          (2)
#define SPI_MISO_1          (3)
/** @}*/

to add each of the above #defines to the pin-assignments group. You can then document this group in more detail using the defgroup command, for example:

/** \defgroup pin-assignments Pin assignments (GPIO row A) 

More detailed description goes here.
*/

(note: the above has not been tested)