Home > database >  Doxygen: document a class in the cpp file with separate source and header directories while using ma
Doxygen: document a class in the cpp file with separate source and header directories while using ma

Time:04-16

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?

CodePudding user response:

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)

  • Related