(Рабочий отчет RWR-2014-08

Малышев А.А.
Система автоматического документирования
Doxygen
Рабочий отчет RWR-2014-08-31.1
Москва, 2014 г.
Оглавление
Аннотация ...............................................................................................3
Установка ................................................................................................3
Запуск ......................................................................................................3
Документирование .................................................................................4
Комманды ...............................................................................................5
Примечания ............................................................................................8
2
Поддерживаемые платформы:
Linux, MacOS, Solaris, Windows;
Поддерживаемые языки:
C++, Си, Objective-C, Python, Java, IDL, PHP, C#, Фортран, VHDL
Аннотация
Программа Doxygen предназначена для автоматического создания
документации к программам.
Установка
sudo apt-get install doxygen
Для установки doxygen под ОС Ubuntu в консоли набираем
команду:
Также есть и графическая версия программы - Doxywizard:
sudo apt-get install doxygen-gui
Запуск
Для того, чтобы doxygen смог сформировать документацию, нужно
создать файл конфигурации, используемый для определения
параметров документирования.
Конечно, можно его создать и вручную, однако есть возможность и
сгенерировать его автоматически. Для этого нужно перейти в папку, где
предполагается хранение документации и набрать команду:
doxygen -g [name]
Параметр name не обязателен.
В вашей папке автоматически появится файл конфигурации. Если
параметр name не был задан, то файл будет называться Doxyfile.
Сам файл содержит очень подробное описание всех параметров,
поэтому заострять внимание на них не будем. Отмечу лишь некоторые,
которые могут быть весьма полезными:
OUTPUT_DIRECTORY
SHOW_INCLUDE_FILES
Определяет директорию, куда будет
сохранена документация.
Если значение = YES - в документацию
включаются include’ы.
3
INPUT
FILE_PATTERNS
EXCLUDE
Используется для задания файлов и
директорий,
где
находятся
документируемые файлы
В этом параметре можно задать шаблон
используемых файлов
В этом параметре можно задать файлы,
которые не будут использоваться для
документирования (удобно задавать в паре
с FILE_PATTERNS)
После настройки файла конфигурации, когда код будет готов к
документированию, в командной строке, находясь в директории, где
находится файл конфигурации, нужно набрать команду для создания
документации:
doxygen [name]
Параметр name можно опустить, если файл конфигурации имеет
стандартное имя Doxyfile.
Чтобы просмотреть документацию, переходим в папку html (если
не меняли имя папки для генерации html-документа) и открываем файл
index.html
Документирование
Для того, чтобы Doxygen мог создать документацию, комментарии
к исходному коду нужно оформлять определённым образом.
Существует два основных типа комментариев: brief и detailed, первый из которых используется для коротких, в одну строчку
комментариев, второй тип - для больших многострочных.
detailed комментарии оформляются так:
/**
* ... text ...
*/
Астериски(звёздочка) между открывающим и
комментариями можно опускать:
закрывающим
4
/**
... text ...
*/
Однострочные комментарии можно делать и так:
///
/// ... text ...
///
Для тех, кто любит делать выделения кусков - комментариев:
/********************************************//**
* ... text
***********************************************/
Можно и так:
/////////////////////////////////////////////////
/// ... text ...
/////////////////////////////////////////////////
Задавать breif описание можно так:
/// Brief description.
/** Detailed description. */
Когда появляется желание вставить описание после определения,
используется такой синтаксис:
int var; /**< Detailed description after the member */
На самом деле оформлений комментариев очень много. Мною
выбран один для хоть какой-то унификации. С прочим оформлением
можно ознакомится здесь.
Комманды
Doxygen поддерживает множество комманд, которые вставляются
в текст комментариев. Суть их проста - расширить возможности
форматирования.
Чтобы вставить комманду, довольно просто написать /command в
тексте комментария, где command - имя команды. Другой синтаксис:
@command .
5
Пример:
/// \brief Brief description.
Команд очень много. Я отобрал полезные:
\author { list of authors }
Оформление автора(-ов) кода
Оформление
версии
программы
Оформление даты. Формат
написание свободный
Оформление примечания
\version { version number }
\date { date description }
\note { text }
\todo { paragraph describing
what is to be done }
Оформление листа TODO
\warning { warning message }
Оформление блока warning
\brief { brief description }
Создание brief комментария
\par [(paragraph
paragraph }
title)]
{
Оформление
параграфа
(удобно
при
написании
форматированного описания)
Пример комментариев:
/*!
* \brief Pretty nice class.
* \details This class is used to demonstrate a number of section
commands.
* \author John Doe
* \author Jan Doe
* \version 4.1a
* \date 1990-2011
* \pre
First initialize the system.
* \bug
Not all memory is freed when deleting an object of this
class.
* \warning Improper use can crash your application
* \copyright GNU Public License.
*/
Результат
6
Пример с применением \par:
/*! \class Test
* Normal text.
*
* \par User defined paragraph:
* Contents of the paragraph.
*
* \par
* New paragraph under the same heading.
*
* \note
* This note consists of two paragraphs.
* This is the first paragraph.
*
* \par
* And this is the second paragraph.
*
* More normal text.
*/
class Test {};
Результат
Полный список комманд с их описанием можно посмотреть здесь.
Более подробная информация
возможностях на сайте разработчика.
о
программе,
настройках,
7
Примечания
 По умолчанию, документация генерируется в двух форматах: HTML
и LaTeX. Так как до LaTeX мы ещё не доросли, в
конфигурационном файле можно выключить генерацию этот вид
документации: параметр GENERATE_LATEX устанавливается в
NO;
 QtCreator помогает с формлением – выделяет особым цветом
комментарии, часть работы выполняет сам (например,
автоматически создаёт блоки-описания для функций, как только вы
начинаете комментировать)ю В нём так же работает
автодополнение. Всё это, конечно, мелочи, однако радуют они;
 Для документирования параметров в функции используется
комманда \param;
 Настоятельно рекомендую воспользоваться коммандой \file
{имя_файла} (например, \file main.cpp). В документации сказано,
что при объявлении глобальных функций, параметров и проч.,
использование этой комманды обязательно!
8