Просмотр исходного текста страницы Использование Doxygen для документирования кода

* [http://www.devexp.ru/2010/02/ispolzovanie-doxygen-dlya-dokumentirovaniya-koda/ Источник]

== Использование Doxygen ==

Использовать Doxygen просто – для этого надо просто запустить программу указав ей путь к файлу с настройками. Файл с настройками представляет собой простой текстовой файл, который можно редактировать как в текстовом редакторе, так и с помощью специальных программ, например [http://sourceforge.net/projects/doxygate Doxygate].

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

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

== Что нужно для работы с Doxygen==

* Doxygen ([http://www.stack.nl/~dimitri/doxygen/manual/index.html Документация])
* make
* GraphViz
* Perl

== Структура папок в проекте ==
* /doxygen
** '''/docs''' – результат работы программы
*** index.html - документация
** /doxyfile 
** /filter – скрипт для преобразования sv -> cpp
** /html – html-шаблон страницы (сейчас не используется)
** '''/img''' – изображения для вставки на страницы документации
*** download_img.sh - скрипт для скачивания картинок
** /scripts
** dofilter.bat – скрипт запуска фильтра для Windows (запускается doxygen`ом)
** dofilter.sh – скрипт запуска фильтра для Unix(запускается doxygen`ом)
** dotest.pl 
** '''Doxyfile.delta''' – Параметры касающиеся конкретного проекта
** Doxyfile.output – входной файл с параметры для Doxygen (слияние .template и .delta)
** '''Doxyfile_sv.template''' – параметры по умолчанию для Doxygen 
** Makefile скрипт для запуска 
* /sv
** '''info.txt''' - файл с декларациями групп/категорий в документации

=== Назначение файлов ===

==== makefile ====
Скрипт для генерации html-отчета
 make

==== Doxyfile.delta====
Файл настроек параметров проекта

<big><source lang="text">
#FILTER_PATTERNS = *.sv=./dofilter.sh *.svh=./dofilter.sh
FILTER_PATTERNS = *.sv=dofilter.bat *.svh=dofilter.bat
STRIP_FROM_PATH = ../
PROJECT_NAME    = UniPro (Pinta)
PROJECT_NUMBER  = 1.0.0
HTML_OUTPUT     = docs
#HTML_FOOTER    = <PATH_DOXYSCR>/html/idv_dox_footer.html
INCLUDE_PATH    = <PATH_PRJ>/../sv <PATH_PRJ>/../sv/pa_sap <PATH_PRJ>/../sv/pa_sap/sequences <PATH_PRJ>/../sv/pa_lm_sap 
                  <PATH_PRJ>/../sv/pa_lm_sap/sequences <PATH_PRJ>/../sv/phy_sap <PATH_PRJ>/../sv/phy_sap/sequences 
                  <PATH_PRJ>/../sv/scoreboard <PATH_PRJ>/../sv/scoreboard/l15_model <PATH_PRJ>/../tb
                  <PATH_PRJ>/../test/test_lib <PATH_PRJ>/../test/vseq_lib
INPUT           = <PATH_PRJ>/../sv <PATH_PRJ>/../sv/pa_sap <PATH_PRJ>/../sv/pa_sap/sequences <PATH_PRJ>/../sv/pa_lm_sap
                  <PATH_PRJ>/../sv/pa_lm_sap/sequences <PATH_PRJ>/../sv/phy_sap <PATH_PRJ>/../sv/phy_sap/sequences
                  <PATH_PRJ>/../sv/scoreboard <PATH_PRJ>/../sv/scoreboard/l15_model <PATH_PRJ>/../tb
                  <PATH_PRJ>/../test/test_lib <PATH_PRJ>/../test/vseq_lib
IMAGE_PATH      = img
</source>
</big>

* для добавления новых папок проекта их нужно включить в переменные INCLUDE_PATH и INPUT
* STRIP_FROM_PATH - путь, который исключается при выводе пути к файлу в документации

=== Файл Doxyfile.output ===

* LAYOUT_FILE = ./doxyfile/idv_doxylayout.xml
* FILE_PATTERNS = *.svh *.sv *.cpp *.c *.h *.vhd *.v *.txt *.md
* FILTER_PATTERNS = *.sv=./filter/idv_doxyfilter_sv.pl *.svh=./filter/idv_doxyfilter_sv.pl

== Пример отчета ==


== Формат комментариев ==

Doxygen поддерживает несколько стилей комментариев:

 '''/**''' 
  * Комментарии, воспринимаемые программой Doxygen
  '''*/'''

 /// Комментарий, воспринимаемые программой Doxygen
 /// продолжение комментария

 int count ;  ///< Счетчик повторов
 int count ;  /**< Счетчик повторов */

== Примеры тегов ==
=== Служебные ===

==== @brief ====

Краткое описание комментируемой сущности.

Пример: 
 /// @brief Функция для поиска пользователя в базе данных

==== @detailed ====

Подробное описание элемента (функции, класса и пр.), то что будет показано, если перейти по ссылке "More..." ("Подробней") в документации.

Пример: 
 /**
  * @detailed Данная функция делает выборку из базы данных по имени пользователя
  * и возвращает структуру с информацией о нем. Ожидается, что соединение с базой 
  * данных установлено и пользователь существует
  */

==== Комбинации @brief и @detailed ====

 /*! \brief Brief description.
  *         Brief description continued.
  *
  *  \detailed Detailed description starts here.
  */

 /*! \brief Brief description.
  *         Brief description continued.
  *
  *  Detailed description starts here.
  */

 /// Brief description.
 /** Detailed description. */

==== @param ====

 \param [(dir)] <parameter-name> { parameter description }

Параметры передаваемые в функции/классе и пр.

Пример: 

 /**
  * A pure virtual member.
  * @param c1 the first argument.
  * @param c2 the second argument.
  */
  virtual void testMeToo(char c1,char c2) = 0;

<big><big><source lang="cpp">/*!
* Copies bytes from a source memory area to a destination memory area,
* where both areas may not overlap.
* @param[out] dest The memory area to copy to.
* @param[in] src The memory area to copy from.
* @param[in] n The number of bytes to copy
*/
void memcpy(void *dest, const void *src, size_t n);
</source>
</big></big>


==== @return ====

Возвращаемое функцией значение.

Пример: 
<pre>@return Информация о пользователе</pre>

==== @note, @warning, @todo ====

 @note
 \todo { paragraph describing what is to be done }
 \warning { warning message }

==== ref ====
 \ref <name> ["(text)"]
Creates a reference to a named section, subsection, page or anchor.


==== Разделы и подразделы ====

* <tt>'''\section''' <section-name> (section title)</tt> - Creates a section with name <section-name>.
* <tt>'''\subsection''' <subsection-name> (subsection title)</tt> - Creates a subsection with name <subsection-name>. The title of the subsection should be specified as the second argument of the \subsection command.
* <tt>'''\subsubsection''' <subsubsection-name> (subsubsection title)</tt>
* <tt>'''\paragraph'''</tt> <paragraph-name> (paragraph title)

==== Страницы и подстраницы ====

 '''\mainpage''' A simple manual 
 '''\page'''  intro Introduction
 '''\subpage''' <name> ["(text)"]

==== Содержание ====

 \tableofcontents

Creates a table of contents at the top of a page, listing all sections and subsections in the page.

 \code [ '{'<word>'}']
 \code{.py}
  class Python:
     pass
  \endcode

====  Диаграммы [http://www.graphviz.org/Gallery.php GraphViz] ====
 /** \mainpage
  * Class relations expressed via an inline dot graph:
  * '''\dot'''
  * digraph example {
  * node [shape=record, fontname=Helvetica, fontsize=10];
  * b [ label="class B" URL="\ref B"];
  * c [ label="class C" URL="\ref C"];
  * b -> c [ arrowhead="open", style="dashed" ];
  * }
  * '''\enddot'''
  * Note that the classes in the above graph are clickable
  * (in the HTML output).
  */

[[Файл:GraphVizExample.jpg|center|750px]]

* [http://www.graphviz.org/Gallery.php Примеры диаграмм GraphViz]

====  Вставка изображений ====

 \image <format> <file> ["caption"] [<sizeindication>=<size>]

Inserts an image into the documentation.

=== Для форматирования ===

== Организация структуры ==

 '''\ingroup''' (<groupname> [<groupname> <groupname>])

Добавлет описания class, file или namespace в соответствующую группу(ы).

 '''\defgroup''' <name> (group title)

Indicates that a comment block contains documentation for a group of classes, files or namespaces. This can be used to categorize classes, files or namespaces, and document those categories. You can also use groups as members of other groups, thus building a hierarchy of groups.

The <name> argument should be a single-word identifier.

 '''\addtogroup''' <name> [(title)]
* создаёт новую группу либо добавляет описание к уже существующей группе
<source lang="cpp">
/*! \addtogroup mygrp
   *  Additional documentation for group 'mygrp'
   *  @{
   */

  /*!
   *  A function
   */
  void func1()
  {
  }

  /*! Another function */
  void func2()
  {
  }

  /*! @} */</source>

=== Примеры ===

 * @defgroup sequences   Sequences
 * @{
 * @brief Sequence classes
 *
 *   @defgroup pa_sap_tx_seq  PA_SAP TX Sequences
 *   @defgroup pa_sap_rx_seq  PA_SAP RX Sequences
 *   @defgroup pa_lm_sap_tx_seq  PA_LM_SAP TX Sequences
 *   ...
 * @}

 /// @file l15_pa_sap_tx_sequences.sv
 /// '''@ingroup''' pa_sap_tx_seq

 /**
  * @class l2_data_base_seq
  * '''@ingroup''' pa_sap_tx_seq
  * @brief Consist of all base task for generate all sequence variants for test cases
  *
  */
 class l2_data_base_seq extends uvm_sequence #(pa_sap_tr);

== Комментирование в стиле Doxygen ==

Doxygen поддерживает несколько стилей комментариев. Я придерживаюсь следующего:

<div><div><pre>/** Комментарии */</pre></div></div>

Обратите внимание, что последовательность символов '''/**''' сообщает программе, что начинается комментарий предназначенный для нее. Начиная с этого места и до завершающих символов '''*/''' следуют комментарии.



Есть несколько директив, которые помогают Doxygen составить грамотную документацию. Вот основные:

{| class=standard cellspacing="5" cellpadding="2" border="1"
| '''@brief'''
| Краткое описание комментируемой сущности.<br /><br />Пример: <pre>@brief Функция для поиска пользователя в базе данных</pre>
|-
| '''@detailed'''
| Подробное описание сущности, то что будет показано, когда вы нажмете в документации рядом с коротким описанием ссылку "Подробней". На мой взгляд использоваться должно как можно реже, в силу того, что короткое описание должно точно отражать идею использования сущности, а использование ее не должно сопровождаться неожиданными предусловиями.<br /><br />Пример: <pre>@detailed Данная функция делает выборку из базы данных
по имени пользователя и возвращает структуру с информацией
о нем. Ожидается, что соединение с базой данных установлено
и пользователь существует</pre>
|-
| '''@param'''
| Параметры передаваемые функции.<br /><br />Пример: <pre>@param name Имя пользователя</pre>
|-
| '''@return'''
| Возвращаемое функцией значение.<br /><br />Пример: <pre>@return Информация о пользователе</pre>
|-
| '''@throw'''
| Исключения выбрасываемые функцией.<br /><br />Пример: <pre>@throw DatabaseError Если произошла ошибка при подключении
к базе данных</pre>
|}

Пример комментариев для класса:

<div><div><pre>/** @brief Класс для работы с базой данных @detailed Осуществляет подключение к базе при создании  и закрывает соединение при уничтожении */
class Database
{
public:
/** @brief Конструктор @param connectionString Строка подключения к базе 
    данных @throw ConnectionError Если подключение не удалось */
	explicit Database(const std::string& connectionString);
/** @brief Поиск пользователя в базе данных @detailed Данная функция делает выборку из базы данных 
 по имени пользователя и возвращает структуру с информацией  о нем. Ожидается, что соединение с базой
 данных установлено  и пользователь существует @param name Имя пользователя @return Информация
 о пользователе @throw DatabaseError Если произошла ошибка при подключении  к базе данных @throw
 InvalidRequest Если пользоваделя в базе не существует */
	CustomerPtr GetCustomer(const std::string& name);
};</pre></div></div>

Этого достаточно для 99% кода, но остается вопрос комментирования на уровне проекта, а не файла. Для этого служат следующие директивы:

{| cellspacing="0" cellpadding="2" border="1"
| '''@mainpage'''
| Основная страница проекта, то с чего начинается просмотр документации.<br /><br />Пример: <pre>@mainpage Приложение для учета пользователей</pre>
|-
| '''@page'''
| Дополнительные страницы проекта. Я рассматриваю их как логически обособленные части проекта.<br /><br />Пример: <pre>@page Database Database
Утилиты для работы с базой данных</pre>
|-
| '''@ref'''
| Ссылки на страницы проекта, с их помощью можно организовать например ссылки с главной страницы проекта на страницы подпроектов.<br /><br />Пример: <pre>@ref Database Утилиты для работы с базой данных</pre>
|}

Для организации четкой структуры я рекомендую в каждом подпроекте создавать файл '''description.h''' в котором будет директива '''@page''', описание для чего нужен этот подпроект и принципы работы с ним.



В свою очередь в корне проекта я также создаю файл '''description.h''' в котором немного рассказано о проекте в целом и приведены ссылки на его части:

<div><div><pre>/** @mainpage Приложение для учета пользователей Состоит из следующих частей: - @ref Database Утилиты для работы с базой данных */</pre></div></div>

Чтобы привести фрагмент кода (например пример работы с классом) используется конструкция '''@code''' – '''@endcode''':

<div><div><pre>/** Пример использования Foo: @code Foo f(); f.Run(); @endcode */</pre></div></div>

Списки можно создавать с помощью символа '''-''' (минус). Пример:

<div><div><pre>/** Список: - Первый пункт - Второй пункт */</pre></div></div>

Перечисления я оформляю так:

<div><div><pre>/** @brief Режимы устройства */
enum Mode
{
	Mode_On,	/**< Включено */
	Mode_Off	/**< Выключено */
};</pre></div></div>

В большинстве случаев приведенных директив достаточно, с полным списком вы можете ознакомиться в [http://www.stack.nl/%7Edimitri/doxygen/commands.html руководстве].

== Ложка дегтя ==

Обратите внимание! Очень ВАЖНО перед объявлением пространства имен повторять его имя в комментарии Doxygen. Похоже на баг (версия 1.6.2), но без этого содержимое пространства не попадет в документацию. Пример:

<div><div><pre>/** namespace A @brief Пространство имен A */
namespace A
{
}</pre></div></div>

Символ @ в конструкции namespace отсутствует!

== Файл с настройками Doxygen ==

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

<div><div><pre>doxygen -g</pre></div></div>

После этого будет сгенерирован файл с именем Doxyfile содержащий настройки по умолчанию. Вы можете отредактировать его под свои нужды, что сделать довольно просто благодаря содержащимся в нем пояснениям.



Рассмотрю некоторые из пунктов которые я изменяю:

{| cellspacing="0" cellpadding="2" border="1"
| '''PROJECT_NAME'''
| Имя проекта.
|-
| '''QUIET'''
| Допустимые значения YES и NO. Я ставлю YES, для того чтобы предупреждения не терялись среди обилия информации о работе программы.
|-
| '''WARN_NO_PARAMDOC'''
| YES для вывода предупреждений о недокументированных аргументах функции.
|-
| '''INPUT'''
| Путь к анализируемому коду. Я рекомендую в корне проекта создать директорию '''docs '''содержащую '''Doxyfile''' с настройками, в таком случае значение этого параметра будет '''../'''
|-
| '''FILE_PATTERNS'''
| Шаблон для имени анализируемых файлов. Поскольку документироваться должны только открытые интерфейсы, то очевидно, что следует анализировать только заголовочные файлы: '''*.h'''
|-
| '''RECURSIVE'''
| Рекурсивно анализировать файлы в поддиректориях – YES.
|-
| '''EXCLUDE_PATTERNS'''
| Исключение из анализа директорий соответствующих маске.<br /><br />Пример: <pre>EXCLUDE_PATTERNS = */.svn/* */build/* */tests/* */sources/*</pre>
|-
| '''HAVE_DOT'''
| YES, если установлен Graphviz и требуется визуализация связей.
|}

Очень разумно будет один раз написать свою конфигурацию для Doxygen и в новых проектах менять лишь один параметр – '''PROJECT_NAME'''.

[[Категория:Doxygen]]