Doxygen ( / д ɒ к ы я dʒ ən / ДОК -см-jən ) [3] является генератор документации [4] [5] [6] [7] и статический анализ инструмент для программного обеспечения исходных деревьев . При использовании в качестве генератора документации Doxygen извлекает информацию из комментариев в специальном формате внутри кода. При использовании для анализа Doxygen использует свое дерево синтаксического анализа для создания диаграмм и диаграмм структуры кода. Doxygen может перекрестно ссылаться на документацию и код, так что читатель документа может легко ссылаться на реальный код.
Разработчики) | Димитри ван Хиш |
---|---|
Первый выпуск | 26 октября 1997 г . [1] |
Стабильный выпуск | 1.9.1 [2] / 8 января 2021 г . |
Репозиторий | |
Написано в | C ++ |
Операционная система | Кроссплатформенность |
Тип | Генератор документации |
Лицензия | GPLv2 |
Веб-сайт | www |
Doxygen - бесплатное программное обеспечение , выпущенное в соответствии с условиями Стандартной общественной лицензии GNU версии 2 (GPLv2).
Дизайн
Как и Javadoc , Doxygen извлекает документацию из комментариев исходного файла. Помимо синтаксиса Javadoc, Doxygen поддерживает теги документации, используемые в наборе инструментов Qt, и может генерировать вывод на языке гипертекстовой разметки ( HTML ), а также в скомпилированной справке Microsoft HTML (CHM), Rich Text Format (RTF), Portable Document Format. (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 @example.com>* @version 1.0 * * @section ЛИЦЕНЗИЯ * * Эта программа является бесплатной; вы можете распространять и / или * изменять его в соответствии с условиями Стандартной общественной лицензии GNU, * опубликованной Free Software Foundation; либо версия 2 * Лицензии, либо (по вашему выбору) любая более поздняя версия. * * Эта программа распространяется в надежде, что она будет полезна, но * БЕЗ КАКИХ-ЛИБО ГАРАНТИЙ; даже без подразумеваемой гарантии ТОВАРНОЙ ПРИГОДНОСТИ или ПРИГОДНОСТИ ДЛЯ ОПРЕДЕЛЕННОЙ ЦЕЛИ. Подробнее см. Стандартную общественную лицензию GNU * по адресу * https://www.gnu.org/copyleft/gpl.html * * @section ОПИСАНИЕ * * Класс времени представляет момент времени. * /class Time { общественность : / ** * Конструктор, который устанавливает время для заданного значения. * * @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
Исходные тексты Doxygen в настоящее время размещены на GitHub , где главный разработчик, Димитри ван Хиш, вносит свой вклад под именем пользователя doxygen. [15] Doxygen написан на C ++ и содержит более 300 000 строк исходного кода . Для лексического анализа стандартный инструмент Lex (или его замена Flex) запускается на более чем 35 000 строк скрипта lex. Разборе инструмент Yacc (или его замена Bison) также используется, но только для второстепенных заданий; основная часть синтаксического анализа языка выполняется собственным кодом C ++. Процесс сборки основан на CMake и также включает некоторые сценарии Python.
Смотрите также
- Сравнение генераторов документации
- Писатель API
- Статический анализ программы
Рекомендации
- ^ ОБЪЯВЛЕНИЕ: doxygen 0.1 Архивировано 4 октября 2011 г. на Wayback Machine , Объявление: первый выпуск Doxygen, системы документации C ++. , Источник: Димитри ван Хиш, Дата: Вс, 26 октября 1997 г., Архив Qt-Interest
- ^ "Руководство Doxygen: Список изменений" . www.doxygen.nl .
- ^ «Руководство Doxygen: часто задаваемые вопросы» . www.doxygen.nl .
- ^ Перкель, Джеффри М. (22 ноября 2015 г.). «Get With the Program: DIY советы по добавлению кода в свой аналитический арсенал» . Ученый ( журнал ). Ученый.
- ^ Сабин, Михаэла (22 ноября 2015 г.). «Доксиген» . OpenComputing ( Wiki ). Университет Нью-Гэмпшира. Архивировано из оригинала на 2015-11-23.
- ^ «Доксиген» . Каталог свободного программного обеспечения ( Wiki ). 2015-11-22.
- ^ «Документация» . Розеттский код ( Wiki ). 2015-11-22.
- ^ «Документация: C» . Розеттский код ( Wiki ). 2015-11-22.
- ^ «Документация: Objective-C» . Розеттский код ( Wiki ). 2015-11-22.
- ^ "Doxygen :: Filter :: Perl - Предварительный фильтр кода Perl для Doxygen - metacpan.org" . metacpan.org .
- ^ а б «Руководство Doxygen: начало работы» . www.doxygen.nl .
- ^ «Инструменты автоматической генерации документации Python API» . python.org wiki ( Вики ). 2015-11-22.
- ^ Браун, Эрик У. «doxypypy: фильтр Doxygen для Python» - через PyPI.
- ^ «Руководство Doxygen: графики и диаграммы» . www.doxygen.nl .
- ^ «доксиген / доксиген» . 9 июня 2021 г. - через GitHub.
Внешние ссылки
- Официальный веб-сайт