Doxygen

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

Исходный код Doxygen размещён на платформе GitHub, где основной разработчик Димитри ван Хис работает под именем «doxygen»^[13]. Doxygen написан на C++ и содержит около 300 тысяч строк исходного кода. Для лексического анализа используется Lex (или его замена Flex), запускаемый через примерно 35 тысяч строк скрипта. Инструмент синтаксического анализа Yacc (или Bison) также применяется, но только для вспомогательных задач. Основная обработка синтаксиса реализована на родном C++ коде. В качестве системы сборки используются CMake и скрипты на Python.

Подобно другим генераторам документации, например Javadoc, Doxygen извлекает информацию как из комментариев, так и из самостоятельных конструкций в коде. Связь комментария с элементом кода достигается непосредственным расположением комментария перед описываемым объектом. В комментариях используется разметка для управления включением и форматированием документации.

Doxygen поддерживает генерацию документации в различных форматах, включая HTML, CHM, RTF, PDF, LaTeX, PostScript и man-страницы.

Возможна генерация диаграмм наследования для C++-классов, а для расширенных схем и графов можно использовать инструмент dot из пакета Graphviz^[14].

Все примеры приведены для языков с С-подобными комментариями, где многострочный комментарий начинается с /*, а однострочный — с //.

Doxygen игнорирует комментарии, если они не размечены специальным образом. Для многострочного комментария маркером служит начало с /** или /*!. Каждый тег разметки начинается со слэша (\) или знака @^[15]. Пример блока комментариев с основными тегами:

/**
 * Описание функции
 * @param p1 Описание параметра p1
 * @param p2 Описание параметра p2
 * @return Описание возвращаемого значения
 */
void foo(int p1, int p2) {}

Блок может быть оформлен различным образом. Часто используют выравнивание звёздочек по левому краю:

/**
 * Описание функции
 * @param p1 Описание параметра p1
 * @param p2 Описание параметра p2
 * @return Описание возвращаемого значения
 */
void foo(int p1, int p2) {}

Также допустим вариант с серией однострочных комментариев. Doxygen поддерживает дополнительный слэш (///) или восклицательный знак (//! ...)^[16].

/// Описание функции
/// @param p1 Описание параметра p1
/// @param p2 Описание параметра p2
/// @return Описание возвращаемого значения
void foo(int p1, int p2) {}

Чтобы разместить документационный комментарий справа от кода, используется добавочный маркер <^[17]. Это позволяет иначе описывать параметры:

/**
 * Описание функции
 */
void foo(int p1 /**< Описание параметра */, int p2 /**< Описание параметра */) {}

Математические формулы могут быть оформлены с помощью синтаксиса LaTeX. Например:

/**
 * Встроенная формула @f$ e^{\pi i}+1 = 0 @f$
 * Отдельно: @f[ e^{\pi i}+1 = 0 @f]
 */

Более развёрнутый пример на C++:

/**
 * @file Time.cpp
 * @module org.wikipedia.util.Time
 * @brief Класс времени
 * @author John Doe <jdoe@example.com>
 * @version 1.0
 * @copyright CC BY-SA или GFDL
 * @sa <a href="https://en.wikipedia.org/wiki/Wikipedia:Copyrights">Wikipedia:Copyrights - Wikipedia</a>
 */

export module org.wikipedia.util.Time;

import org.wikipedia.core;
import org.wikipedia.util.Date;

using org::wikipedia::core::ISerializable;

/**
 * @namespace org::wikipedia::util
 * @brief Пространство имён утилит
 */
export namespace org::wikipedia::util {

/**
 * @class Time
 * @brief Представляет момент времени
 * @author John Doe
 *
 * Класс Time представляет количество времени, прошедшее с эпохи UNIX.
 *
 * @extends Date
 * @implements ISerializable
 */
class Time : public Date, public ISerializable {
private:
    int64_t millis; ///< миллисекунд с 1 января 1970 года
public:
    /**
     * Создать новый объект Time с временем от 1 января 1970 года
     * @param millis количество миллисекунд
     */
    explicit Time(int64_t millis): 
        millis{millis} {}

    /**
     * Получить новый экземпляр с текущим временем
     * @return Экземпляр
     */
    nodiscard
    static Time now() {
        // ...
    }

    /**
     * Получить количество миллисекунд, представляемых объектом Time
     * @return int64_t — количество миллисекунд
     */
    nodiscard
    int64_t getTime() const noexcept {
        return millis;
    }
};

}