使用文件或类在doxygen中记录类？ [英] use file or class for documenting classes in doxygen?

问题描述

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

This surely is a noob question, but I can't find an answer in Doxygen documentation. I'm not sure whether using:

@file

或

@class

。

原因是如果我把文件，所有的注释只出现在文件选项卡，但不是在类选项卡（每个）。

The reason is that if I put file, then all the comments appear in the Files tab only, but not in the Classes tab (per each).

对于cpp它没关系，我只是使用文件，它是好的，但如果我在标题中使用文件和类（文件开头和类的声明开始之前的类声明）然后我在生成的文档中的类的重复条目...

For cpp it's ok, I just use file and it's good, but if I use both file and class in the header (file at the beginning and class right before the start of the class declaration) then I get duplicated entries for the class in the generated documentation...

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

What I'm doing wrong? Any suggestions? Ideas?

谨慎，
Alex

Regards, Alex

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

I run into a new problem now. In order to avoid circular dependecies I declare my class twice in a header file (probably this is not the best way to avoid circular dependencies but it normally works for me), for instance:

#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包围的东西似乎不是很喜欢...

As you can see, I have a forward declaration prior my "real" declaration. Now if I use @class, Doxygen complains about inconsystency issues related with this class, although it generates the documentation for the class. My guess is that anything that is surrounded by #ifdef or #ifndef Doxygen does not seem to like it very much...

推荐答案

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

I usually use neither, unless I want to specify an alternate include path or something like that. Normally it looks like this:

/// 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），可能提供一个类的引用。

This is actually equivalent to using @class, so the answer to your question is yes, you should use @class when documenting classes. If your header file doesn't contain anything else, you probably shouldn't document it at all, as the documentation would only say something like "this file contains the declaration of the class SomeClass" anyway. If the file contains something more, like friend functions, you should document the file too (obviously, using @file), possibly providing a reference to the class.

这篇关于使用文件或类在doxygen中记录类？的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！