использовать файл или класс для документирования классов в doxygen?

Это, конечно, нубский вопрос, но я не могу найти ответ в документации Doxygen. Я не уверен, что использую:

@файл

or

@сорт

при документировании моих заголовочных файлов.

Причина в том, что если я помещаю файл, то все комментарии появляются только на вкладке «Файлы», а не на вкладке «Классы» (по каждому).

Для 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, похоже, не очень нравится...


c++ doxygen
person AlejandroVK    schedule 09.02.2011    source источник
comment
Вы документируете класс? Если это так, вам следует использовать докситег @class. Вы документируете файл? Если это так, вам следует использовать докситег @file.   -  person James McNellis    schedule 09.02.2011
comment
Мое определение класса находится в заголовочном файле, который является... файлом... что делать тогда?   -  person AlejandroVK    schedule 09.02.2011

Ответы (1)


arrow_upward
1
arrow_downward

Обычно я не использую ни то, ни другое, если только не хочу указать альтернативный путь включения или что-то в этом роде. Обычно это выглядит так:

/// 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), возможно, предоставив ссылку на класс.

person Sergei Tachenov    schedule 09.02.2011