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

Материал из SRNS
Перейти к: навигация, поиск
(Пример из жизни)
 
(не показаны 8 промежуточных версий 1 участника)
Строка 7: Строка 7:
 
Для html-представления документации, размещаемого на web-серверах, существует удобный способ организации поиска (при помощи создаваемого Doxygen'ом PHP-модуля) и ссылок на внешнюю документацию.
 
Для html-представления документации, размещаемого на web-серверах, существует удобный способ организации поиска (при помощи создаваемого Doxygen'ом PHP-модуля) и ссылок на внешнюю документацию.
  
Doxygen - консольная программа в духе классической Unix. Она работает подобно компилятору, анализируя исходные тексты и создавая документацию. [ Пример.]
+
Doxygen - консольная программа в духе классической Unix. Она работает подобно компилятору, анализируя исходные тексты и создавая документацию.
 +
 
  
 
== Что требуется установить для полноценной работы ==
 
== Что требуется установить для полноценной работы ==
 +
  
 
=== Doxygen ===
 
=== Doxygen ===
  
 
Основная программа
 
Основная программа
 +
  
 
=== Graphiz ===
 
=== Graphiz ===
  
 
[http://ru.wikipedia.org/wiki/Graphviz Graphviz] – это свободно распространяемый пакет утилит для визуализации данных. Нам он нужен для того, чтобы Doxygen мог показать в документации отношения наследования, графы вызовов и прочую информацию в виде наглядных изображений.
 
[http://ru.wikipedia.org/wiki/Graphviz Graphviz] – это свободно распространяемый пакет утилит для визуализации данных. Нам он нужен для того, чтобы Doxygen мог показать в документации отношения наследования, графы вызовов и прочую информацию в виде наглядных изображений.
 +
  
 
=== LaTeX ===
 
=== LaTeX ===
  
 
При установленном пакете того или иного LaTeX-дистрибутива, Doxygen конвертирует TeX-разметку в комментариях в изображения, а затем вставляет их в итоговый отчет. Также генерирует TeX-файлы, а затем PDF.
 
При установленном пакете того или иного LaTeX-дистрибутива, Doxygen конвертирует TeX-разметку в комментариях в изображения, а затем вставляет их в итоговый отчет. Также генерирует TeX-файлы, а затем PDF.
 +
  
 
=== Doxywizard ===
 
=== Doxywizard ===
Строка 1418: Строка 1423:
 
  \interface - документирование IDL интерфейса
 
  \interface - документирование IDL интерфейса
 
  \package - документирование пакета на языке Java
 
  \package - документирование пакета на языке Java
 +
  
 
== Востребованные команды ==
 
== Востребованные команды ==
  
=== Документирование структур, переменных и т.д. ===
 
  
=== Документирование функции ===
+
=== Комментирование структур, переменных и т.д. ===
 +
 
 +
Переменные часто удобно объединять в группы:
 +
<source lang="c">
 +
/** @name Аккумуляторы и их триггеры */
 +
quint32 R2; ///< Первичный акк.  \f$ I^2 + Q^2 \f$
 +
quint64 R4; ///< Первичный акк.  \f$ (I^2 + Q^2)^2 \f$
 +
 
 +
quint32 R2_acum; ///< Вторичный аккумулятор R2
 +
quint64 R4_acum; ///< Вторичный аккумулятор R4
 +
 +
quint32 R2_acum_copy; ///< Триггер R2_acum
 +
quint64 R4_acum_copy; ///< Триггер R4_acum
 +
//@}
 +
</source>
 +
 
 +
 
 +
=== Комментирование функции ===
 +
 
 +
<source lang="c">
 +
/**
 +
Позволяет установить оценку дисперсии (мощности шумовой составляющей) корреляционных сумм и
 +
зафиксировать её.
 +
@param PoMe - указатель на структуру данных блока оценки с/ш
 +
@param stdn2_IQ - устанавливаемое значение оценки дисперсии квадратур
 +
@return 0, если прошло успешно, 1, если предлагаемое число после сдвига не влазиет в 32 разряда
 +
*/
 +
int SetVariancePowerMeasure(PowerMeasure_struct *PoMe, quint32 stdn2_IQ ){
 +
        if (__CLZ(stdn2_IQ) >= x_stdn2_shift){ // Если предлагаемое число можно сдвинуть, не переполнив 32 разряда
 +
                PoMe->x_stdn2_est = stdn2_IQ;
 +
                // В случае увеличения порядка фильтра добавить сюда PoMe->x_stdn2_extr = stdn2_IQ;
 +
                PoMe->x_stdn2_est_shifted = stdn2_IQ<<x_stdn2_shift;
 +
                return 0;
 +
        }else  return 1;
 +
}
 +
</source>
 +
 
  
 
=== Вставка TeX-формул ===
 
=== Вставка TeX-формул ===
  
 
Для вставки TeX-формулы используются команды <code>\f$ ... \f$</code> и <code>\f[ ... \f] </code>, которые обрамляют TeX-разметку:
 
Для вставки TeX-формулы используются команды <code>\f$ ... \f$</code> и <code>\f[ ... \f] </code>, которые обрамляют TeX-разметку:
 
  
 
Выражение в тексте:
 
Выражение в тексте:
Строка 1452: Строка 1492:
 
</source>
 
</source>
  
 +
 +
=== Bug, ToDo, Warning, Note ===
 +
 +
Одноименные команды вставляют одноименные заметки. Далее doxygen формирует отдельные списки, по которым можно быстро найти интересующее место в коде.
 +
 +
<source lang="c">
 +
/**
 +
@warning Не трогать значение этой переменной
 +
@todo Переписать функцию под новую структуру данных
 +
@bug Ошибочно работает при x<0
 +
@note Подробнее изложено в рабочем журнале
 +
*/
 +
</source>
  
 
== Пример из жизни ==
 
== Пример из жизни ==
Строка 2110: Строка 2163:
 
   </div>
 
   </div>
 
</div>
 
</div>
 +
 +
 +
== Проблемы ==
 +
 +
Doxygen, во всяком случае мой, некорректно работает с директивами препроцессора <code>#if, #ifdef</code> и т.п. Пока удается решить эту проблему перечислением в Doxyfile (поле PREDEFINED) значений всех используемых в таких выражениях define'ов.
 +
  
 
== Ссылки ==
 
== Ссылки ==

Текущая версия на 21:40, 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).

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

//! Оценка вектора состояния СС за дисперсией квадратурных компонент
int x_stdn2_est;

Существует множество вариантов оформления комментариев:

  • Возможно использовать комментарии в стиле системы JavaDoc, применяемой при документировании исходных текстов на языке Java:
/**
* Оценка вектора состояния СС за дисперсией квадратурных компонент
*/
int x_stdn2_est;

или так

/*!
* Оценка вектора состояния СС за дисперсией квадратурных компонент
*/
int x_stdn2_est;

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

/*!
Оценка вектора состояния СС за дисперсией квадратурных компонент
*/
int x_stdn2_est;

  • Еще один вариант - использование дополнительных знаков "/" или "!" в каждой строке (QT-Style):
///
/// Оценка вектора состояния СС за дисперсией квадратурных компонент
///
int x_stdn2_est;
или

//!
//! Оценка вектора состояния СС за дисперсией квадратурных компонент
//!
int x_stdn2_est;


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

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

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

или

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

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

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


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

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

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

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


[править] Востребованные команды

[править] Комментирование структур, переменных и т.д.

Переменные часто удобно объединять в группы:

 /** @name Аккумуляторы и их триггеры */
 quint32 R2; ///< Первичный акк.  \f$ I^2 + Q^2 \f$
 quint64 R4; ///< Первичный акк.  \f$ (I^2 + Q^2)^2 \f$

 quint32 R2_acum; ///< Вторичный аккумулятор R2
 quint64 R4_acum; ///< Вторичный аккумулятор R4
 
 quint32 R2_acum_copy; ///< Триггер R2_acum
 quint64 R4_acum_copy; ///< Триггер R4_acum
 //@}


[править] Комментирование функции

/**
Позволяет установить оценку дисперсии (мощности шумовой составляющей) корреляционных сумм и
зафиксировать её.
@param PoMe - указатель на структуру данных блока оценки с/ш
@param stdn2_IQ - устанавливаемое значение оценки дисперсии квадратур
@return 0, если прошло успешно, 1, если предлагаемое число после сдвига не влазиет в 32 разряда
*/

int SetVariancePowerMeasure(PowerMeasure_struct *PoMe, quint32 stdn2_IQ ){
        if (__CLZ(stdn2_IQ) >= x_stdn2_shift){ // Если предлагаемое число можно сдвинуть, не переполнив 32 разряда
                PoMe->x_stdn2_est = stdn2_IQ;
                // В случае увеличения порядка фильтра добавить сюда PoMe->x_stdn2_extr = stdn2_IQ;
                PoMe->x_stdn2_est_shifted = stdn2_IQ<<x_stdn2_shift;
                return 0;
        }else   return 1;
}


[править] Вставка 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


[править] Bug, ToDo, Warning, Note

Одноименные команды вставляют одноименные заметки. Далее doxygen формирует отдельные списки, по которым можно быстро найти интересующее место в коде.

/**
@warning Не трогать значение этой переменной
@todo Переписать функцию под новую структуру данных
@bug Ошибочно работает при x<0
@note Подробнее изложено в рабочем журнале
*/

[править] Пример из жизни

Пример документирования файлов PowerMeasure.c и PowerMeasure.h. Результат можно подглядеть тут.



[править] Проблемы

Doxygen, во всяком случае мой, некорректно работает с директивами препроцессора #if, #ifdef и т.п. Пока удается решить эту проблему перечислением в Doxyfile (поле PREDEFINED) значений всех используемых в таких выражениях define'ов.


[править] Ссылки

Персональные инструменты
Пространства имён

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