Question

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

@file

or

@class

when documenting my header files.

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).

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?

Regards,
Alex

Edit: 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

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…

Answer 1

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 {

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.