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 , и может генерировать выходные данные на языке гипертекстовой разметки ( HTML ), а также в скомпилированной HTML-справке Microsoft (CHM), расширенном текстовом формате (RTF), переносимом формате документов. (PDF), LaTeX , PostScript или справочные страницы .
Языки программирования , поддерживаемые 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 Описание входного параметра метода или функции @param ... @return Описание возвращаемого значения */Многие программисты любят отмечать начало каждой строки пробелом-звездочкой-пробелом, как показано ниже, но в этом нет необходимости.
/** * < Короткое однострочное описание> * * <Подробное описание > * <При необходимости может охватывать несколько строк или абзацев> * * @param Описание входного параметра метода или функции * @param ... * @return Описание возвращаемое значение */Многие программисты избегают использования комментариев в стиле C и вместо этого используют однострочные комментарии в стиле C++. Doxygen принимает комментарии с дополнительной косой чертой как комментарии Doxygen.
/// < Короткое описание в одну строку> /// /// <Длинное описание> /// <При необходимости может охватывать несколько строк или абзацев> /// /// @param Описание входного параметра метода или функции /// / @param ... /// @return Описание возвращаемого значенияНиже показано, как можно документировать исходный файл C++ .
/** * @file * @author John Doe <[email protected]> * @version 1.0 * * @section LICENSE * * Эта программа является свободным программным обеспечением; вы можете распространять его и/или * изменять его в соответствии с условиями Стандартной общественной лицензии GNU, * опубликованной Фондом свободного программного обеспечения; либо версия 2 * Лицензии, либо (по вашему выбору) любая более поздняя версия. * * Данная программа распространяется в надежде, что она будет полезна, но * БЕЗ КАКИХ-ЛИБО ГАРАНТИЙ; даже без подразумеваемой гарантии * ТОВАРНОЙ ПРИГОДНОСТИ или ПРИГОДНОСТИ ДЛЯ ОПРЕДЕЛЕННОЙ ЦЕЛИ. Дополнительную информацию см. в GNU * General Public License по адресу * https://www.gnu.org/copyleft/gpl.html * * @section ОПИСАНИЕ * * Класс времени представляет момент времени. */время учебы { общественность : /** * Конструктор, который устанавливает время в заданное значение. * * @param timemillis — количество миллисекунд , * прошедшее с 1 января 1970 года. */ Time ( int timemillis ) { // код } /** * Получить текущее время. * * @return Объект времени, установленный на текущее время. */ static Time now () { // код } }; Альтернативный подход к документированию параметров показан ниже. Он выдаст ту же документацию.
/** * Конструктор, который устанавливает время в заданное значение. */ Time ( int timemillis ///< Количество миллисекунд, прошедших с 1 января 1970 года.> ) { // код } Также возможна более богатая разметка. Например, добавьте уравнения с помощью команд LaTeX :
/** * * Встроенное уравнение @f$ e^{\pi i}+1 = 0 @f$ * * Отображаемое уравнение: @f[ e^{\pi i}+1 = 0 @f] * * /Исходники Doxygen в настоящее время размещены на GitHub , где главный разработчик Дмитрий ван Хиш вносит свой вклад под именем пользователя «doxygen». [15] Doxygen написан на C++ и состоит из около 300 000 строк исходного кода . Для лексического анализа стандартный инструмент Lex (или его замена Flex) запускается с помощью примерно 35 000 строк сценария lex. Инструмент синтаксического анализа Yacc ( или его замена Bison) также используется, но только для второстепенных задач; основная часть синтаксического анализа языка выполняется собственным кодом C++. Процесс сборки основан на CMake , а также включает в себя некоторые скрипты Python.
.svg/1280px-Free_and_open-source_software_logo_(2009).svg.png){kind=logo}