通過Doxygen中的宏定義的文檔函數

Question

我有一個不存在但通過宏定義的類：

#define DEFCLASS(name,datatype) Class name { \
    public: \
        void clear(); \
        datatype obj; \
    };
DEFMETHOD(StringContainer, const char*)

...

StringContainer foo("hi!");

當然它應該是使用模板實現的，但我沒有寫它，我無法改變它，大型代碼庫依賴它。

現在的問題是，我想在doxygen中記錄StringContainer。 但是，它不是真正存在的類，所以如果我這樣做：

/*!
    \class StringContainer
    \brief A string container

    \fn void StringContainer::clear()
    \brief Clears the container
*/

我得到了doxygen警告：

warning: documented function `StringContainer::clear' was not declared or defined.

並且文檔不包含該功能。 我知道這有點棘手，但有沒有辦法強制doxygen有“信念”並為StringContainer創建文檔，即使它沒有在源代碼中定義？

解

有可能創建假的.h文件，使doxygen相信一個類存在，同時防止構建系統包含它。 這些文件可以具有.dox擴展名。 這樣，我將創建一個包含類定義和文檔的.dox文件：

class StringContainer {
public:
    /*! Removes the contents of the container. */
    void clear();
    const char *obj;
};

該文件實際上不會包含在構建系統中，其唯一目的是記錄StringContainer。

Answer 1

我必須為現有的代碼庫做很多事情，我發現使用“EXPAND_AS_DEFINED”配置選項將為您解決這個問題。 在Doxygen配置文件中，設置以下內容：

EXPAND_AS_DEFINED = DEFCLASS

只要包含“DEFCLASS”定義的文件是Doxygen的輸入，這就可以工作。 （即，這不適用於“STDMETHOD”之類的東西，因為您可能不包含將“STDMETHOD”定義為Doxygen輸入的文件）

我在VS 2010中嘗試了如下，並且能夠在沒有警告的情況下編譯和運行Doxygen。

這是一個例子：

Base.h文件：

#pragma once

#define DEFCLASS(name,datatype) class name { \
    public: \
        name(){} \
        void clear(){}; \
        datatype obj; \
    };

DEFCLASS(StringContainer, const char*)


/*!
    \class StringContainer
    \brief A string container

    \fn void StringContainer::clear()
    \brief Clears the container
*/

Base.cpp文件：

#include "Base.h"

int main()
{
    StringContainer foo;
    foo.clear();


    return 0;
}

DoxygenTest.doxygen

MACRO_EXPANSION        = YES
EXPAND_ONLY_PREDEF     = YES
EXPAND_AS_DEFINED      = DEFCLASS

Answer 2

如果你在doxygen配置中將MACRO_EXPANSION設置為“yes”（http://www.star.bnl.gov/public/comp/sofi/doxygen/config.htm），doxygen將“看到”StringContainer。

Answer 3

我建議閱讀doxygen手冊的這一部分： http ： //www.doxygen.org/preprocessing.html 。 解釋如何處理DECLARE_INTERFACE和STDMETHOD宏的部分與您想要的非常相似。

因此，如果您不希望在單獨的文件中編寫虛擬類，這可以是一種替代解決方案。