Doxygen question for board/periph configuration header files

Development archive
1

Hi,

finally, I'm trying to improve the doxygen documentation of board*.h/periph*.h configuration files for my ESP8266 port.

I tried to use the @name command together with @{ and }@ , to group all definitions that are related to a certain peripheral interface, e.g., I2C interface.

It seems that the resulting HTML code differs for such group definitions.

For example, in

http://riot-os.org/api/boards_2native_2include_2board_8h.html

the definition "LED handlers" and "MTD emulation configuration" are documented in the same way with the @name command. However, the output differs for them.

Is this a problem of doxygen or do I miss something?

Regards Gunar

2

Hi,

it seems that the style of the output changes either if a variable or function declaration is part of such group.

But this is not always the case. For example, even though there are such declarations in

http://riot-os.org/api/boards_2native_2include_2board_8h.html

"LED handlers" and "MTD emulation configuration" look different.

Regards Gunar

3

Hi Gunar,

Hi,

it seems that the style of the output changes either if a variable or function declaration is part of such group.

But this is not always the case. For example, even though there are such declarations in

http://riot-os.org/api/boards_2native_2include_2board_8h.html

I find it useful to enable XML output in Doxygen and inspect the resulting XML. This will indicate if its a structure problem (meaning you messed up) or a rendering problem (meaning Doxygen messed up).

In this case you are right, and the XML shows "LED Handlers" and "MTD emulation configuration" both correspond to `<sectiondef kind="user-defined">` elements, with no difference other than their contents.

I think that what happens is that Doxygen presentation logic automatically detects groups with preprocessor definitions only and nests them under a "Macros" section. Unfortunately, there's not much that can be done to customize this behavior (see https://www.stack.nl/~dimitri/doxygen/manual/customize.html)

Regards,

Juan.

4

Hi Juan,

thanks for your answer.

In the meantime I could figure out that the enabled subgrouping causes this problem if all group members are of the same type.

I have opened issue #9849 which describes the problem in detail and how it could be solved. It's just a suggestion for better output quality. Let's see what RIOT's maintainers think about it.

Regards Gunar