Доксиген

Бесплатное программное обеспечение для создания документации по программному обеспечению из исходного кода
Разработчик(и)Димитрий ван Хееш
Первоначальный выпуск26 октября 1997 г .; 27 лет назад [1] ( 1997-10-26 )
Стабильный релиз
1.13.1 [2]  / 2 января 2025 г. ; 0 дней назад ( 2 января 2025 г. )
Репозиторий
  • github.com/doxygen/doxygen
Написано вС++
Операционная системаКроссплатформенный
ТипГенератор документации
ЛицензияGPLv2
Веб-сайтdoxygen.nl

Doxygen ( / ˈ d ɒ k s i ə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

Исходные коды Doxygen в настоящее время размещены на GitHub , где основной разработчик, Димитри ван Хеш, вносит свой вклад под именем пользователя «doxygen». [18] Doxygen написан на C++ и состоит из около 300 000 строк исходного кода . Для лексического анализа стандартный инструмент Lex (или его замена Flex) запускается с помощью примерно 35 000 строк скрипта lex. Инструмент синтаксического анализа Yacc (или его замена Bison) также используется, но только для второстепенных задач; основная часть языкового синтаксического анализа выполняется нативным кодом C++. Процесс сборки основан на CMake и также включает в себя некоторые скрипты Python .

Смотрите также

Ссылки

  1. ^ АНОНС: doxygen 0.1 Архивировано 4 октября 2011 г. на Wayback Machine , Анонс: первый выпуск Doxygen, системы документирования C++. , От: Dimitri van Heesch, Дата: воскресенье, 26 октября 1997 г., Архив Qt-interest
  2. ^ "Doxygen release 1.13.1". 2 января 2025 г. Получено 2 января 2025 г.
  3. ^ «Руководство Doxygen: часто задаваемые вопросы». www.doxygen.nl .
  4. ^ Перкель, Джеффри М. (2015-11-22). «Get With the Program: DIY tips for added coding to your analysis armestion». The Scientist ( журнал ). The Scientist.
  5. ^ Сабин, Михаэла (22.11.2015). "Doxygen". OpenComputing ( Wiki ). Университет Нью-Гемпшира. Архивировано из оригинала 23.11.2015.
  6. ^ "Doxygen". Каталог свободного программного обеспечения ( Wiki ). 2015-11-22.
  7. ^ "Документация". Rosetta Code ( Wiki ). 2015-11-22.
  8. ^ "Документация: C". Rosetta Code ( Wiki ). 2015-11-22.
  9. ^ "Документация: Objective-C". Rosetta Code ( Wiki ). 2015-11-22.
  10. ^ "Doxygen::Filter::Perl - Предварительный фильтр кода Perl для Doxygen - metacpan.org". metacpan.org .
  11. ^ ab "Руководство Doxygen: Начало работы". www.doxygen.nl .
  12. ^ "Автоматические инструменты генерации документации API Python". python.org wiki ( Wiki ). 2015-11-22.
  13. ^ Браун, Эрик В. «doxypypy: фильтр Doxygen для Python» – через PyPI.
  14. ^ "Руководство Doxygen: Графики и диаграммы". www.doxygen.nl .
  15. ^ Doxygen: Специальные команды
  16. ^ Doxygen: Документирование кода - §Блоки комментариев для языков типа C
  17. ^ Doxygen: Документирование кода - § Размещение документации после членов
  18. ^ "doxygen/doxygen". 9 июня 2021 г. – через GitHub.
  • Официальный сайт
Взято с "https://en.wikipedia.org/w/index.php?title=Doxygen&oldid=1253756977"