Особенности документации Doxygen для MATLAB скриптов

Документирование программ MATLAB в Doxygen имеет свою специфику, поэтому нам пригодятся далеко не все возможности Doxygen. Далее следует краткое описание основных моментов при комментировании кода MATLAB.

1. Разделы документации в Doxygen
Здесь привожу описание наиболее часто используемых мной тегов разметки, отвечающих за структурные компоненты документации (разделы, подразделы, todo-список, список ошибок и проч.).

1.1. Базовое описание скрипта или функции
Перечисленные ниже теги разметки используются в основном в самом начале файла. Пример типичного скрипта:

%> @file kmvComplCorrRndDataGenerator_func.m
%> @brief This routine does the generation of complex correlated data.
%> 
%> @author Mikhail V. Konnik
%> @date   13 May 2010
%> @bug    Data is generated in ROWS, must be in Columns
%> @todo   The following:
%> - random vectors must contain data in rows, not columns
%>
%> @section randchol Cholesky decomposition
%> In order to start the study of random...

Далее описание используемых тегов разметки:

@file programname.m
В самом начале кода - для именования файла, который мы документируем, чтобы была возможность ссылаться на него в других документах просто по имени.

@brief Description of the script of function
Краткое описание реализуемых идей функции или скрипта; используется в начале кода и при описании функции.

@author Vasily Pupkin
Кто написал функцию или скрипт (и на кого вешать всех собак, если она не работает :-))

@date 1 May 2010
Когда вы последний раз редактировали программу (я всегда правлю это на текущую дату, когда что-то меняю в программе).

@bug Bug description
Что надо доделать или описание времянок в коде.

@todo List of things to do
Список того, что нужно сделать в программе или пожелания самому себе по улучшению функционала программы.


1.2. Особенности документирования функций MATLAB в Doxygen
Пример типичного описание функции:

%> ======================================================================
%> @brief Description of the function
%>
%> @c The @c algorithm:
%>  - first step
%>  - second step
%> 
%> @param arg1 Meaning of the parameter1
%> @param arg2 Meaning of the parameter2
%>
%> @retval out1  What is the product of the function?
% ======================================================================
function atm = sim_make_atm_params(arg1, arg2)

Здесь нужно отметить, что arg1 и arg2 должны быть в вашей функции теми же, иначе Doxygen будет ругаться следующими словами:

/home/dot/matlab/aorta-dev/AOJan07-making/development/sim_make_atm_params.m:10: Warning: argument 'arg1' of command @param is not found in the argument list of sim_make_atm_params(in nx, in phase_screenwidth, in D_over_r0)
/home/dot/matlab/aorta-dev/AOJan07-making/development/sim_make_atm_params.m:10: Warning: argument 'arg2' of command @param is not found in the argument list of sim_make_atm_params(in nx, in phase_screenwidth, in D_over_r0)
/home/dot/matlab/aorta-dev/AOJan07-making/development/sim_make_atm_params.m:10: Warning: argument 'arg3' of command @param is not found in the argument list of sim_make_atm_params(in nx, in phase_screenwidth, in D_over_r0)
/home/dot/matlab/aorta-dev/AOJan07-making/development/sim_make_atm_params.m:10: Warning: The following parameters of sim_make_atm_params(in nx, in phase_screenwidth, in D_over_r0) are not documented:
parameter 'nx'
parameter 'phase_screenwidth'
parameter 'D_over_r0'

Описание использованных тегов:
@brief
Краткое описание реализуемых идей функции

@param arg1 Описание параметра
Описание параметра arg1 и его назначения.

@retval What is the product
Описание возвращаемого функцией значения.





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

@section reflabel The title of the section
Раздел в документации к скрипту с меткой reflabel (на эту метку можно потом ссылаться с помощью @ref reflabel ) и заголовком The title of the section. Как правило, содержит солидный кусок текста с кучей формул.


@subsection reflabel The title of the subsection
Подраздел в документации к скрипту с меткой reflabel.
Содержит кусок описания поменьше.

@attention text
Выносной абзац, подчёркивающий важность участка текста.

@ref reflabel
Ссылка на особый участок документации (в другом файле или в том же самом), например:

See @ref reflabel about particular implementation.

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

See @ref reflabel "this page" about particular implementation.

Выглядеть будет так: See this page about particular implementation, где this page будет гиперссылкой на нужный нам раздел.


@verbatim
Дословное цитирование кода в документации Doxygen.
Пример:

%> @verbatim
%>% Matlab comment ignored by doxygen
%>%> a = magic(5);
%> @endverbatim

Полезно вставлять в документацию особенно сложные или навороченные куски кода с подробными комментариями.


@c TheВыделение слова The курсивом.

@b The Выделение слова The полужирным шрифтом.


%> Making the list:
%> - first thing
%> - next thing
Оформление ненумерованного (bullet-list) списка.

Something @n The Перенос слова The на другую строку (новая строка в Doxygen, оно же newline)


\f$ \LaTeX formula \f$
Это одна из самых нужных вещей: комментарий к функции бесполезен, если в нём не приведены математические описания алгоритма. Можно использовать только внутристрочные формулы вроде $\xi=1$ и нельзя использовать нумерованные формулы в окружении \begin{equation}. Вот пример документации с формулами:

%> @section randchol Cholesky decomposition and Generation of Correlated Random Variables
%> In order to start the study of random variables and covariation matrices, we need to generate the random variables/matrices with given variance/covariance matrix.
%> For instance, we need a matrix of random variables that are a liner combination of other variables. Let's generate \f$X = (X_1, \dots, X_n)\f$, where X would be normal Gaussian noise \f$N(0, \Sigma)\f$. Suppose that each random variable initially is \f$Z_i \sim N(0,1)\f$, and we need to construct correlated normal random variables from \f$Z_i\f$.

В ЛаТеХе они смотрятся замечательно, в HTML файле - в виде рисунков.

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

#---------------------------------------------------------------------------
# configuration options related to the LaTeX output
#---------------------------------------------------------------------------
GENERATE_LATEX = YES
LATEX_OUTPUT = latex
LATEX_CMD_NAME = latex
MAKEINDEX_CMD_NAME = makeindex
COMPACT_LATEX =
PAPER_TYPE = a4
EXTRA_PACKAGES = amssymb,amsfonts,amsmath,mathtext
LATEX_HEADER =
PDF_HYPERLINKS = YES
USE_PDFLATEX = YES
LATEX_BATCHMODE = NO
LATEX_HIDE_INDICES = NO
#---------------------------------------------------------------------------

Красным выделен параметр, который нужно поменять - вписать туда все нужные пакеты, чтобы и в LaTeX, и в HTML выводе появились сложные формулы (в HTML они появятся картинками).

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

%> @image html image.jpg

После этого в файле Doxyfile ищем и правим переменную:

IMAGE_PATH = ./reference/images/

иначе Doxygen будет ругаться при компиляции, что не нашёл изображение, следующими матерными выражениями:

home/latitude/matlab/aorta/simulator/development/ppg_circ.m:9: Warning: image file image.jpg is not found in IMAGE_PATH: assuming external image.

Этот и другие трюки можно прочесть в сих басурманских свитках на вражеской мове.

Увлекательное чтиво
Продолжение скандальных разоблачений Doxygen со стрельбой, погоней и голыми женщинами можно прочитать по этой ссылке.