Doxygen: document a class in the cpp file with separate source and header directories while using macros to define namespaces

Question

I'm trying to document a library with the following files:

include/mylib/mylib_global.h
include/mylib/SomeClass.h
source/SomeClass.cpp
Doxyfile

include/mylib/mylib_global.h:

#pragma once
#define MYLIB_NAMESPACE_BEGIN namespace mylibns {
#define MYLIB_NAMESPACE_END   }

include/mylib/SomeClass.h:

#pragma once
#include "mylib_global.h"

MYLIB_NAMESPACE_BEGIN

class SomeClass
{
public:
    SomeClass();
};

MYLIB_NAMESPACE_END

source/SomeClass.cpp:

#include "mylib/SomeClass.h"

MYLIB_NAMESPACE_BEGIN

/*!
 * \class SomeClass
 * This is a sample class.
 */

/*!
 * This is a constructor.
 */
SomeClass::SomeClass()
{
}

MYLIB_NAMESPACE_END

Doxyfile:

PROJECT_NAME = mylib
INPUT = .
RECURSIVE = YES
MACRO_EXPANSION = YES

Doxygen produces the following warning:

Doxygen version used: 1.9.3 (c0b9eafbfb53286ce31e75e2b6c976ee4d345473)
[...]
include/mylib/SomeClass.h:7: warning: Compound mylibns::SomeClass is not documented.
*** Doxygen has finished

If I do any of the following, it works:

• Move the cpp to include/. But I don't want it there.
• Move the documentation to the header. But I'd like to keep it short.
• namespace mylibns { instead of the macro in the cpp. But I want the namespace to be configurable.
• MACRO_EXPANSION = NO. But that would also remove the namespace from the documentation.
• Explicitly state the namespace in the doxygen comment: \class mylibns::SomeClass. However that only helps with this specific issue (doxygen also fails to resolve overloaded functions).

Things that don't help:

• Specifying any combination of longer paths for the INPUT parameter.
• EXTRACT_ALL = YES
• CLANG_ASSISTED_PARSING = YES

How do I do this properly?

Answer 1

In the file source/SomeClass.cpp you have:

#include "mylib/SomeClass.h"

but the file SomeClass.h is located in include/mylib so you have to tell doxygen where to find the include file. This can be done by means of the setting:

INCLUDE_PATH = include

(analogous what you probably have done for the compiler with the setting like -I include)