использовать файл или класс для документирования классов в Doxygen? - PullRequest
Новая
       7

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

0 голосов
/ 09 февраля 2011

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

@ file

или

@ class

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

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

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

1 Ответ

1 голос
/ 09 февраля 2011

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

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

...