Doxygen не документирует основную функцию в main.cpp

У меня есть main.cpp, который содержит структуру, некоторые глобальные константы и основную функцию.

Я запустил doxygen, и единственная документация, которую я получаю в выходном файле index.html, относится к моей структуре.

Я хочу, чтобы doxygen документировал в этом файле index.html мой main(). Что я делаю неправильно?

    /// Definition of Pi
    const auto Pi = 3.141592653589793238462643383279502884197169399;

    /// \struct myStruc
    /// \brief myStruc description
    ///
    struct myStruc
    {
         /// Comments inside myStruc
    };

    /// \file

    /// \brief  Main function
    /// \param  argc An integer argument count of the command line arguments
    /// \param  argv An argument vector of the command line arguments
    /// \return an integer 0 upon exit success
    int main(int argc, char** argv)
    {
        /// Comments I would like to be documented in as well
        return 0;
    }

person user1496542    schedule 20.08.2012    source источник


Ответы (4)


Это потому, что вы документируете глобальный объект, который doxygen по умолчанию не документирует. Из руководства по doxygen (выделено мной):

Чтобы задокументировать член класса C++, вы также должны задокументировать сам класс. То же самое относится и к пространствам имен. Чтобы задокументировать глобальную функцию C, typedef, enum или определение препроцессора, вы должны сначала задокументировать файл, который их содержит (обычно это будет заголовочный файл, поскольку этот файл содержит информацию, которая экспортируется в другой источник). файлы).

Давайте повторим это, потому что это часто упускается из виду: для документирования глобальных объектов (функций, определений типов, перечислений, макросов и т. д.) вы должны документировать файл, в котором они определены. Другими словами, должны по крайней мере быть

/*! \file */ 

or a

/** @file */ 

строка в этом файле.

Поэтому попробуйте добавить одну из двух строк выше в файл main.cpp.

person Chris    schedule 20.08.2012
comment
Итак, я добавил один из тех, которые вы перечислили выше, но он по-прежнему не показывает описание моего main(), как я дал в примере выше... он просто документирует константы и структуру (как и раньше), но все еще ничего из внутри моего основного(). - person user1496542; 20.08.2012
comment
Ну, вы упоминаете константы и структуры, но в вашем примере их нет. Как правило, это отсутствие документации к файлу, поэтому функции не отображаются в документации. Если это не решает проблему, то я не знаю, что предложить, не видя остальной части вашего кода. Опубликуйте минимальный автономный пример, воспроизводящий проблему, с которой вы столкнулись. - person Chris; 20.08.2012
comment
хорошо, я только что обновился. То, что сработало, я не думал, что мне нужно включать, поэтому приношу свои извинения. Но я также попробовал предложения, данные в ответе ниже, но все равно не повезло:/ - person user1496542; 20.08.2012
comment
Я все еще получаю ожидаемый результат (функция main задокументирована), когда запускаю doxygen в вашем примере кода. Попробуйте использовать файл конфигурации doxygen по умолчанию. Если это решит проблему, попробуйте сравнить файл конфигурации, который вы используете, с файлом по умолчанию и посмотрите, чем они отличаются. Если это не решит проблему, то нам не хватает некоторой информации. - person Chris; 20.08.2012

Убедитесь, что HIDE_IN_BODY_DOCS установлено на NO, и используйте что-то вроде этого:

/// \file

/// \brief  Main function
/// \param  argc An integer argument count of the command line arguments
/// \param  argv An argument vector of the command line arguments
/// \return an integer 0 upon exit success
int main(int argc, char** argv)
{
  /// Comments I would like to be documented in as well
  return 0;
}
person doxygen    schedule 20.08.2012
comment
Я попробовал то, что вы предложили, и до сих пор нет документации по основным функциям :( - person user1496542; 20.08.2012
comment
Какую версию doxygen вы использовали? (У меня это отлично работает с 1.8.2) - person doxygen; 21.08.2012

Для меня я должен был убедиться, что у меня есть этот набор:

ПОКАЗАТЬ_ФАЙЛЫ = ДА

Все ваши глобальные функции появятся на вкладке «Файлы» внутри каждого файла. Кроме того, это помогает, если у вас есть @file или \file, определенный в верхней части вашего кода.

person Someone13    schedule 03.08.2013
comment
Большое спасибо. Несмотря на все технические достижения, найти правильный ответ практически невозможно. это должно получить +1000000 - person Kovalex; 20.11.2019

Из онлайн-руководства в разделе «Документация в других местах»: http://www.doxygen.nl/manual/docblocks.html#specialblock

«Doxygen позволяет размещать блоки документации практически в любом месте (исключение находится внутри тела функции или внутри обычного блока комментариев в стиле C)».

Это имеет некоторый смысл, потому что мельчайшие детали того, КАК работает функция (ее реализация), обычно нежелательны. Я считаю, что цель doxygen состоит в том, чтобы помочь в документации, которая легко доступна для поиска, чтобы позволить программистам находить, где что находится, и искать, что они делают (и какие параметры передаются в него, что он возвращает и т. д.), чтобы узнать, как их использовать. , но не как это на самом деле реализовано. Это потребует фактического просмотра источника функции (который также доступен в файлах, сгенерированных doxygen). Кроме того, если вы заметили, все примеры (я думаю) показывают документацию в файлах заголовков, в которых отсутствует какая-либо реализация, что заставляет меня полагать, что документация предназначена для файлов заголовков, но инструмент дает вам гибкость, чтобы поместить ее в также исходные файлы.

Во всяком случае, это моя точка зрения. Кто-нибудь думает иначе?

person radensb    schedule 12.03.2013