Doxygen demands that an include-guard be documented

Question

Please do not mind the strangeness of the following minimal example (I would have to make it much larger to justify why I am doing things this way):

File test.cpp:

#include "a.h"

int main() {
  return 0;
}

File a.h:

namespace N { // without namespace all is well!
#include "b.h"
}

File b.h:

/// \file

#ifndef GUARD
#define GUARD

struct A {};
#define CMD 5 // without this, all is well!

#endif

Doxygen 1.8.11 complains:

warning: Member GUARD (macro definition) of file a.h is not documented.

The first interesting thing is that the warning mentions a.h. The second one is that if either of the commented lines is removed, the warning disappears. What is going on here?

Deaminate

a.h doesn't have include guards ? – Reld

@old_mountain Only for minimality of the example. – Deaminate

Answer 1

You may use conditional documentation to suppress Doxygen warnings like this:

//b.h
/// \file

//! @cond SuppressGuard
#ifndef GUARD
#define GUARD
//! @endcond

struct A {};
//! @cond SuppressCmd
#define CMD 5 // without this, all is well!
//! @endcond

//! @cond SuppressGuard
#endif
//! @endcond

Note that I wrapped #endif with conds, because otherwise you'll get if-endif mismatch warning:

/home/user/doxygen/b.h:13: warning: More #endif's than #if's found.

Amaryl

This is a workaround. But what was going on? Why did the warning disappear when I did not define CMD? – Deaminate