Доксиген

Разработчик(и)	Дмитрий ван Хиш
Первоначальный выпуск	26 октября 1997 г ( 1997-10-26 )
Стабильная версия	1.11.0   / 20 мая 2024 г ( 20 мая 2024 г. )
Репозиторий	github .с /doxygen /doxygen
Написано в	С++
Операционная система	Кросс-платформенный
Тип	Генератор документации
Лицензия	лицензия GPLv2
Веб-сайт	doxygen.nl

Doxygen ( / ˈ d ɒ k s i dʒ ən / DOK -see-jən ) это генератор документации и статического анализа инструмент деревьев исходного кода программного обеспечения . При использовании в качестве генератора документации 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 , C++ , C# , D , Фортран , IDL , Java , Objective-C , Перл , PHP , Питон , и ВХДЛ . Другие языки могут поддерживаться с помощью дополнительного кода.

Doxygen работает на большинстве Unix-подобных систем, macOS и Windows .

Первая версия Doxygen заимствовала код из ранней версии DOC++, разработанной Роландом Вундерлингом и Малте Цёклером в Институте Цузе в Берлине . Позже код Doxygen был переписан Дмитрием ван Хешем.

Doxygen имеет встроенную поддержку для создания диаграмм наследования для классов C++. Для более сложных диаграмм и графиков Doxygen может использовать инструмент «точка» из Graphviz .

Пример кода

Общий синтаксис комментариев к документации заключается в том, что комментарий начинается с дополнительной звездочки после ведущего разделителя комментариев '/*':

/**
<A short one line description>

<Longer description>
<May span multiple lines or paragraphs as needed>

@param  Description of method's or function's input parameter
@param  ...
@return Description of the return value
*/

Многие программисты любят отмечать начало каждой строки пробелом-звездочкой-пробелом, как показано ниже, но в этом нет необходимости.

/**
 * <A short one line description>
 *
 * <Longer description>
 * <May span multiple lines or paragraphs as needed>
 *
 * @param  Description of method's or function's input parameter
 * @param  ...
 * @return Description of the return value
 */

Многие программисты избегают использования комментариев в стиле C и вместо этого используют однострочные комментарии в стиле C++. Doxygen принимает комментарии с дополнительной косой чертой как комментарии Doxygen.

/// <A short one line description>
///
/// <Longer description>
/// <May span multiple lines or paragraphs as needed>
///
/// @param  Description of method's or function's input parameter
/// @param  ...
/// @return Description of the return value

Ниже показано, как C++ можно документировать исходный файл .

Скриншот того, как будет выглядеть результат в HTML.

/**
 * @file
 * @author  John Doe <[email protected]>
 * @version 1.0
 *
 * @section LICENSE
 *
 * This program is free software; you can redistribute it and/or
 * modify it under the terms of the GNU General Public License as
 * published by the Free Software Foundation; either version 2 of
 * the License, or (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful, but
 * WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
 * General Public License for more details at
 * https://www.gnu.org/copyleft/gpl.html
 *
 * @section DESCRIPTION
 *
 * The time class represents a moment of time.
 */

class Time {

    public:

       /**
        * Constructor that sets the time to a given value.
        *
        * @param timemillis is a number of milliseconds
        *        passed since Jan 1, 1970.
        */
       Time (int timemillis) {
           // the code
       }

       /**
        * Get the current time.
        *
        * @return A time object set to the current time.
        */
       static Time now () {
           // the code
       }
};

Альтернативный подход к документированию параметров показан ниже. Он выдаст ту же документацию.

       /**
        * Constructor that sets the time to a given value.
        */
       Time (int timemillis ///< Number of milliseconds passed since Jan 1, 1970.>
            )
       {
           // the code
       }

Также возможна более богатая разметка. Например, добавьте уравнения с помощью LaTeX команд :

/**
 *
 * An inline equation @f$ e^{\pi i}+1 = 0 @f$
 *
 * A displayed equation: @f[ e^{\pi i}+1 = 0 @f]
 *
 */

Источник и разработка Doxygen

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

См. также

• Сравнение генераторов документации
• API-писатель
• Статический анализ программы

Внешние ссылки

• Официальный сайт