Doxygen: multiple \mainpage blocks in a C++ project

Question

I wasn't able to determine what the behavior of doxygen is regarding the \mainpage section, in two cases:

1. If you specify no \mainpage section, does it use any other page instead and if so how is this picked?
2. What if two files both specify a \mainpage section?

Answer 1

The \mainpage command specifies content used to customise the index page, so if you lack one it's just a blank page with the normal Doxygen header and footer.

I think the safest thing to say about having multiple \mainpage commands is that it is undefined in the classic sense of yielding unpredictable results depending on version and platform. Similarly, I've had weird results when I accidentally created more than one \page command with the same page name.

Further Thought

Prompted by answering another Doxygen question, remember you can get Doxygen to obey the preprocessor directives so you can have #if conditionals protect the multiple mainpage directives and run different config files over the same code base, where the config files define one of several flag values.

I have used this generate the docs from different perspectives approach to publish Macintosh and Windows-oriented versions of the same reference.