使用文件或类来记录 doxygen 中的类？答案

【问题标题】：use file or class for documenting classes in doxygen?使用文件或类来记录 doxygen 中的类？
【发布时间】：2011-02-09 15:22:55
【问题描述】：

这肯定是一个菜鸟问题，但我在 Doxygen 文档中找不到答案。我不确定是否使用：

@文件

或

@类

在记录我的头文件时。

原因是如果我放置文件，那么所有 cmets 仅出现在“文件”选项卡中，而不出现在“类”选项卡中（每个）。

对于 cpp 没关系，我只使用文件，这很好，但如果我在标题中同时使用文件和类（文件在开头，类在类声明开始之前），那么我会得到重复的条目生成文档中的类...

我做错了什么？有什么建议？想法？

问候，亚历克斯

编辑：我现在遇到了一个新问题。为了避免循环依赖，我在头文件中声明了我的类两次（可能这不是避免循环依赖的最佳方法，但它通常对我有用），例如：

#ifndef EU_SOFIA_KPI_COMMON_ABSTRACTTHREAD_DECL
#define EU_SOFIA_KPI_COMMON_ABSTRACTTHREAD_DECL

namespace eu_sofia_kpi_common
{
    class KPI_CPP_API AbstractThread;
}

#define EU_SOFIA_KPI_COMMON_ABSTRACTTHREAD_DECL_END
#endif EU_SOFIA_KPI_COMMON_ABSTRACTTHREAD_DECL

#ifdef EU_SOFIA_KPI_COMMON_ABSTRACTTHREAD_DECL_END
#ifndef EU_SOFIA_KPI_COMMON_ABSTRACTTHREAD_DEF
#define EU_SOFIA_KPI_COMMON_ABSTRACTTHREAD_DEF

namespace eu_sofia_kpi_common
{

    class KPI_CPP_API AbstractThread
    {

    public:
        AbstractThread();
        virtual ~AbstractThread();
        ///start method, derived classes must implement this method to initialize their boost::shared_ptr<boost::thread> pointer member object
        virtual int start() = 0;
        //stop method
        virtual void stop() = 0;

    protected:
        ///Pointer to a boost thread to be inherited and that children classes must use in the implementation of the start and stop methods
        boost::shared_ptr<boost::thread> m_thread;
    };

}

#endif EU_SOFIA_KPI_COMMON_ABSTRACTTHREAD_DEF
#endif EU_SOFIA_KPI_COMMON_ABSTRACTTHREAD_DECL_END

如您所见，我的“真实”声明之前有一个前向声明。现在，如果我使用@class，Doxygen 会抱怨与此类相关的不一致问题，尽管它会生成该类的文档。我的猜测是，任何被#ifdef 或#ifndef Doxygen 包围的东西似乎都不太喜欢它......

【问题讨论】：

你在记录一个类吗？如果是这样，您应该使用@class doxytag。您在记录文件吗？如果是这样，您应该使用@file doxytag。
我的类定义在一个头文件中，它是……一个文件……那该怎么办？

标签： c++ doxygen

【解决方案1】：

我通常都不使用，除非我想指定备用包含路径或类似的东西。通常它看起来像这样：

/// Tunables loader.
/** This class contains a set of functions for loading tunables from
 * file. Usually you only need one QuaTunablesLoader object in your
 * program. Once its work is done, you can safely destroy it.
 * 
 * ... blah, blah, blah ...
 * */
class QuaTunablesLoader {

这实际上相当于使用@class，所以你的问题的答案是肯定的，你应该在记录类时使用@class。如果您的头文件不包含任何其他内容，您可能根本不应该记录它，因为文档只会说“此文件包含类 SomeClass 的声明”之类的内容。如果文件包含更多内容，例如友元函数，您也应该记录该文件（显然，使用@file），可能提供对类的引用。

【讨论】：