Doxygen — различия между версиями

Материал из SRNS
Перейти к: навигация, поиск
(→‎Наиболее часто используемые команды)
Строка 1308: Строка 1308:
 
   </div>
 
   </div>
 
</div>
 
</div>
 +
 +
 +
==Комментирование исходного текста==
 +
Практически любой элемент программы (класс, функция, переменная) может быть задокументирован в системе Doxygen.<br>
 +
Документирование выполняется на основе двух видов комментариев:<br>
 +
* краткий (brief)
 +
* и полный (detailed).
 +
 +
Краткие комментарии обычно описывают предназначение комментируемого элемента, а полные содержат информацию по его использованию и функционированию и чаще всего являются многострочными.<br>
 +
К каждому элементу программы не может быть привязано более одного краткого и полного комментария.<br>
 +
Для документирования какого-либо элемента программы, соответствующий комментарий располагают перед этим элементом в тексте программы. Например:
 +
 +
    //! Конструктор класса
 +
    Test();
 +
 +
Существует множество вариантов оформления комментариев:<br>
 +
1. Возможно использовать комментарии в стиле системы JavaDoc, применяемой при документировании исходных текстов на языке Java:
 +
 +
/**
 +
* ... текст ...
 +
*/
 +
2. Второй вариант:
 +
/*!
 +
* ... текст ...
 +
*/
 +
 +
как и для предыдущего случая, знаки "*" не обязательны для промежуточных строк:
 +
/*!
 +
  ... текст ...
 +
*/
 +
 +
3. еще один вариант - использование дополнительных знаков "/" или "!" в каждой строке
 +
///
 +
/// ... текст ...
 +
///
 +
 +
или
 +
 +
//!
 +
//!... текст ...
 +
//!
 +
 +
 +
По умолчанию любой многострочный комментарий является подробным. Для объявления кратких комментариев можно так же использовать несколько методов:<br>
 +
 +
1. Использование команды \brief в блоке комментария:
 +
/*! \brief краткий комментарий.
 +
*        краткий комментарий.
 +
*
 +
*  после пустой строки начинается подробный комментарий.
 +
*/
 +
 +
2.Для однострочных комментариев:
 +
/// краткое описание.
 +
/** Полное описание. */
 +
или
 +
//! краткое описание.
 +
 +
//! многострочное
 +
//! подробное описание.
 +
 +
 +
Иногда желательно расположить комментарий после, либо на одной строке с описываемым элементом. Для такого случая так же существуют несколько возможных способов:<br>
 +
 +
1.    int var; /*!< Подробный комментарий */
 +
2.    int var; /**< Подробный комментарий */
 +
3.    int var; //!< Подробный комментарий
 +
4.            //!<
 +
5.    int var; ///< Подробный комментарий
 +
          ///<
 +
6.    int var; //!< Краткий комментарий
 +
7.    int var; ///< Краткий комментарий
 +
 +
 +
Обычно предполагается, что документирующие комментарии находятся рядом с документируемым элементом. Однако, Doxygen позволяет поместить комментарий практически в любой части файла, связав его с каким-либо элементом. В этом случае необходимо указывать в блоке комментария ряд специальных команд.<br>
 +
Например так будет выглядеть описание класса Test, размещенное в любом месте файла:<br>
 +
 +
/*! \class Test
 +
    \brief Тестовый класс.
 +
 
 +
    Полное описание класса.
 +
*/
 +
 +
Кроме команды \class, можно использовать множество других:<br>
 +
\struct - документирует структуру
 +
\union - документирует объединение
 +
\enum - документирует перечисление
 +
\fn - документирует функцию
 +
\var - документирует переменную
 +
\def - документирует макрос подстановки #define
 +
\file - документирует файл
 +
\namespace - документирует пространство имен.
 +
\typedef - документирование объявления типа
 +
\interface - документирование IDL интерфейса
 +
\package - документирование пакета на языке Java
 +
  
 
== Востребованные команды ==
 
== Востребованные команды ==

Версия 20:51, 19 апреля 2011

Doxygen — это кроссплатформенная система документирования исходных текстов, которая поддерживает C++, Си, Objective-C, Python, Java, IDL, PHP, C#, Фортран, VHDL и, частично, D.

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

Doxygen имеет встроенную поддержку генерации документации в формате HTML, LaTeX, man, RTF и XML. Также вывод может быть легко сконвертирован в CHM, PostScript, PDF.

Для html-представления документации, размещаемого на web-серверах, существует удобный способ организации поиска (при помощи создаваемого Doxygen'ом PHP-модуля) и ссылок на внешнюю документацию.

Doxygen - консольная программа в духе классической Unix. Она работает подобно компилятору, анализируя исходные тексты и создавая документацию. [ Пример.]

Содержание

Что требуется установить для полноценной работы

Doxygen

Основная программа

Graphiz

Graphviz – это свободно распространяемый пакет утилит для визуализации данных. Нам он нужен для того, чтобы Doxygen мог показать в документации отношения наследования, графы вызовов и прочую информацию в виде наглядных изображений.

LaTeX

При установленном пакете того или иного LaTeX-дистрибутива, Doxygen конвертирует TeX-разметку в комментариях в изображения, а затем вставляет их в итоговый отчет. Также генерирует TeX-файлы, а затем PDF.

Doxywizard

Параметры создания документации читаются из конфигурационного файла, имеющего простой текстовый формат (см. ниже). Для упрощения манипуляций с конфигурационным файлом (а он содержит довольно много настроек), существует несколько утилит с графическим интерфейсом. Одна из них, doxywizard, поставляется вместе с Doxygen.


Комментирование исходного текста

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

  • краткий (brief)
  • и полный (detailed).

Краткие комментарии обычно описывают предназначение комментируемого элемента, а полные содержат информацию по его использованию и функционированию и чаще всего являются многострочными.
К каждому элементу программы не может быть привязано более одного краткого и полного комментария.
Для документирования какого-либо элемента программы, соответствующий комментарий располагают перед этим элементом в тексте программы. Например: 

   //! Конструктор класса
   Test();

Существует множество вариантов оформления комментариев:
1. Возможно использовать комментарии в стиле системы JavaDoc, применяемой при документировании исходных текстов на языке Java: 

/**
* ... текст ...
*/
2. Второй вариант:
/*!
* ... текст ...
*/

как и для предыдущего случая, знаки "*" не обязательны для промежуточных строк:
/*!
 ... текст ...
*/

3. еще один вариант - использование дополнительных знаков "/" или "!" в каждой строке
///
/// ... текст ...
///

или

//!
//!... текст ...
//!


По умолчанию любой многострочный комментарий является подробным. Для объявления кратких комментариев можно так же использовать несколько методов:

1. Использование команды \brief в блоке комментария:
/*! \brief краткий комментарий.
*         краткий комментарий.
*
*  после пустой строки начинается подробный комментарий.
*/

2.Для однострочных комментариев:
/// краткое описание.
/** Полное описание. */
или
//! краткое описание.

//! многострочное
//! подробное описание.


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

1.    int var; /*!< Подробный комментарий */
2.    int var; /**< Подробный комментарий */
3.    int var; //!< Подробный комментарий
4.             //!<
5.    int var; ///< Подробный комментарий
         ///<
6.    int var; //!< Краткий комментарий
7.    int var; ///< Краткий комментарий


Обычно предполагается, что документирующие комментарии находятся рядом с документируемым элементом. Однако, Doxygen позволяет поместить комментарий практически в любой части файла, связав его с каким-либо элементом. В этом случае необходимо указывать в блоке комментария ряд специальных команд.
Например так будет выглядеть описание класса Test, размещенное в любом месте файла:

/*! \class Test
    \brief Тестовый класс.
 
    Полное описание класса.
*/

Кроме команды \class, можно использовать множество других:

\struct - документирует структуру
\union - документирует объединение
\enum - документирует перечисление
\fn - документирует функцию
\var - документирует переменную
\def - документирует макрос подстановки #define
\file - документирует файл
\namespace - документирует пространство имен.
\typedef - документирование объявления типа
\interface - документирование IDL интерфейса
\package - документирование пакета на языке Java


Востребованные команды

Документирование структур, переменных и т.д.

Документирование функции

Вставка TeX-формул

Для вставки TeX-формулы используются команды \f$ ... \f$ и \f[ ... \f] , которые обрамляют TeX-разметку:


Выражение в тексте:

/** Всё гениальное просто: \f$ E = mc^2 \f$ */


Выражение по центру, с новой строки:

/** Воспользуемся дискриминатором
\f[
u_{d,k} = - atan{frac{Q_k}{I_k}},
\f]
его характеристики хорошо изучены, работа наглядна.
*/


Для расширенного синтаксиса нужно дополнить опцию в Doxyfile'e:

EXTRA_PACKAGES         = amssymb,amsfonts,amsmath,mathtext

Ссылки

Источник — «https://www.srns.ru/index.php?title=Doxygen&oldid=499»
Персональные инструменты
Пространства имён

Варианты
Действия
SRNS Wiki
Рабочие журналы
Приватный файлсервер
QNAP Сервер
Инструменты