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

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

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

Я хочу, чтобы doxygen записывал в файл index.html файл my 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;
    }

Ответ 1

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

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

Повторите это, потому что его часто пропускают: документировать глобальные объекты (функции, typedefs, enum, макросы и т.д.), вы должны документировать файл, в котором они определены. Другими словами, должно быть хотя бы <
/*! \file */ 
или
/** @file */ 
в этом файле.

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

Ответ 2

Убедитесь, что для параметра 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;
}

Ответ 3

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

SHOW_FILES = YES

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

Ответ 4

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

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

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

Это мой взгляд в любом случае. Кто-нибудь думает по-другому?