Description

Using the current doxygen release 1.8.15 to generate the documentation results into 12700 warnings with our current master!

What are the problems:

1. Setex-style headers in markdown files and comments throw the warning: multiple use of section label 'xyz' while adding section, (first occurrence: <file>, line <n>).. It seems to be a bug: Multiple use of section label warning for Setex-stype headers in markdown doxygen/doxygen#6779.
   (20 warnings)
   There is already a PR issue #6779 Multiple use of section label warning for Setex-stype headers in markdown doxygen/doxygen#6780 which will fix the problem.

2. doxygen 1.8.15 seems to be much more nit-picking. Constructs like the following throw warnings: Member XYZ (<type>) of <file | group> is not documented. where <type> can be function, macro definition, enumeration, typedef, variable:

   /**
    * @name    UART configuration
    * @{
    */
   #define UART_NUMOF          (1U)
   #define UART_PIN_RX         GPIO_PIN(0,8)
   #define UART_PIN_TX         GPIO_PIN(0,6)
   /** @} */

   (8960 warnings in files)
   (3720 warnings in groups)

   These are: 52 enums, 21 typedefs, 134 functions, 609 variables and 11998 macro definitions

3. mainpage.md is not handled as root node in the navigation tree anymore. Instead the root node is My Project and the contents of mainpage.md appears as its own section entry and the sections in mainpage.md as subsection entries. Although the title of the root node can be set with PROJECT_NAME = RIOT, it doesn't help to get mainpage.md as root node. USE_MDFILE_AS_MAINPAGE = src/mainpage.md should be set to guarantee that contents of mainpage.md is used as contents of index.html. But it does not help for the navigation tree.

   Seems to be a bug in doxygen, I have opened a bug report there navtree root node if PROJECT_NAME is empty doxygen/doxygen#6789

4. For *.md documents, the TOC is not generated.
   New configuration variable TOC_INCLUDE_HEADINGS has to be set to a value > 0.

Steps to reproduce the issue

Install/download doxygen 1.8.15 or the current master and execute

make doc