Разработчик(и) | Димитрий ван Хееш |
---|---|
Первоначальный выпуск | 26 октября 1997 г ( 1997-10-26 ) | [1]
Стабильный релиз | 1.13.1 [2] / 2 января 2025 г. ( 2 января 2025 г. ) |
Репозиторий |
|
Написано в | С++ |
Операционная система | Кроссплатформенный |
Тип | Генератор документации |
Лицензия | GPLv2 |
Веб-сайт | doxygen.nl |
Doxygen ( / ˈ d ɒ k s i dʒ ən / DOK -see-jən ) [3] — это генератор документации [4] [5] [6] [7] и инструмент статического анализа для деревьев исходного кода программного обеспечения . При использовании в качестве генератора документации Doxygen извлекает информацию из специально отформатированных комментариев в коде. При использовании для анализа Doxygen использует свое дерево синтаксического анализа для создания диаграмм и схем структуры кода. Doxygen может перекрестно ссылаться на документацию и код, так что читатель документа может легко ссылаться на фактический код.
Doxygen — это свободное программное обеспечение , выпущенное на условиях GNU General Public License версии 2 (GPLv2).
Как и Javadoc , Doxygen извлекает документацию из комментариев исходного файла. В дополнение к синтаксису Javadoc, Doxygen поддерживает теги документации, используемые в наборе инструментов Qt , и может генерировать вывод в формате HyperText Markup Language ( HTML ), а также в форматах Microsoft Compiled HTML Help ( CHM ), Rich Text Format ( RTF ), Portable Document Format ( PDF ), LaTeX , PostScript или man pages .
Языки программирования, поддерживаемые Doxygen, включают C , [8] C++ , C# , D , Fortran , IDL , Java , Objective-C , [9] Perl , [10] PHP , [11] Python , [12] [13] и VHDL . [11] Другие языки могут поддерживаться с помощью дополнительного кода.
Doxygen работает на большинстве Unix-подобных систем, macOS и Windows .
Первая версия Doxygen заимствовала код из ранней версии DOC++, разработанной Роландом Вундерлингом и Мальте Цёклером в Институте Цузе в Берлине . Позднее код Doxygen был переписан Димитри ван Хеешем.
Doxygen имеет встроенную поддержку для создания диаграмм наследования для классов C++. Для более сложных диаграмм и графиков Doxygen может использовать инструмент "точка" из Graphviz . [14]
Общий синтаксис комментариев к документации заключается в том, что комментарий начинается с дополнительной звездочки ( *
) или восклицательного знака ( !
) после начального разделителя комментариев ' /*
':
/** <Короткое описание в одну строку ><Более длинное описание> <При необходимости может охватывать несколько строк или абзацев>@param someParameter Описание входного или выходного параметра метода или функции @param ... @return Описание возвращаемого значения */
Все команды в документации начинаются с обратной косой черты ( \
) или знака @ ( @
). [15]
Многие программисты любят отмечать начало каждой строки символами пробел-звездочка-пробел, как показано ниже, но это не обязательно.
/** * <Короткое описание в одну строку> * * <Более длинное описание> * <При необходимости может занимать несколько строк или абзацев> * * @param someParameter Описание входного или выходного параметра метода или функции * @param ... * @return Описание возвращаемого значения */
Многие программисты избегают использования комментариев в стиле C и вместо этого используют однострочные комментарии в стиле C++. Doxygen принимает комментарии с дополнительным последующим слешем ( /
) или восклицательным знаком ( !
) как комментарии Doxygen. [16]
/// < Короткое описание в одну строку > /// /// <Более длинное описание> /// <При необходимости может занимать несколько строк или абзацев> /// /// @param someParameter Описание входного или выходного параметра метода или функции /// @param ... /// @return Описание возвращаемого значения
//! <Короткое описание в одну строку > //! //! <Более длинное описание> //! <При необходимости может занимать несколько строк или абзацев> //! //! @param someParameter Описание входного или выходного параметра метода или функции //! @param ... //! @return Описание возвращаемого значения
Ниже показано, как можно документировать исходный файл C++.
/** * @file * @brief Заголовочный файл класса Time. * @author John Doe <jdoe@example.com> * @version 1.0 * @copyright CC BY-SA или GFDL. * @sa <a href="https://en.wikipedia.org/wiki/Wikipedia:Copyrights">Википедия:Авторские права - Википедия</a> *//** * Класс времени представляет момент времени. * * @author John Doe */ class Time { public : /** * Конструктор, который устанавливает время на заданное значение. * * @param timeMillis Количество миллисекунд, прошедших с 1 января 1970 года. */ explicit Time ( long long timeMillis ) { // код } /** * Получить текущее время. * * @return Объект времени, установленный на текущее время. */ static Time now () { // код } private : long long m_timeMillis ; ///< Миллисекунды, прошедшие с 1 января 1970 года. };
<
Чтобы разместить документацию после участников, в блоке комментариев требуется дополнительный маркер. [17]
Ниже показан альтернативный подход к документированию параметров. Он даст ту же документацию.
/** * Конструктор, который устанавливает время на заданное значение. */ explicit Time ( long long timeMillis /**< Количество миллисекунд, прошедших с 1 января 1970 года. */ ) { // код }
/** * Конструктор, который устанавливает время на заданное значение. */ explicit Time ( long long timeMillis ///< Количество миллисекунд, прошедших с 1 января 1970 года. ) { // код }
Также возможна более богатая разметка. Например, добавьте уравнения с помощью команд LaTeX :
/** * * Встроенное уравнение @f$ e^{\pi i}+1 = 0 @f$ * * Отображаемое уравнение: @f[ e^{\pi i}+1 = 0 @f] * */
Исходные коды Doxygen в настоящее время размещены на GitHub , где основной разработчик, Димитри ван Хеш, вносит свой вклад под именем пользователя «doxygen». [18] Doxygen написан на C++ и состоит из около 300 000 строк исходного кода . Для лексического анализа стандартный инструмент Lex (или его замена Flex) запускается с помощью примерно 35 000 строк скрипта lex. Инструмент синтаксического анализа Yacc (или его замена Bison) также используется, но только для второстепенных задач; основная часть языкового синтаксического анализа выполняется нативным кодом C++. Процесс сборки основан на CMake и также включает в себя некоторые скрипты Python .