11/15/2010

Особенности документации 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 со стрельбой, погоней и голыми женщинами можно прочитать по этой ссылке.

2 комментария:

  1. Надо бы таки осилить этот вот Doxygen — судя по твоим заметкам, таки полезная штука, если проект достаточно большой. Наверняка же в работе пригодится…

    Ну, а теперь перейдём к дебагу статьи:

    Интересно, а что с текстом «@param arg1 Описание параметра»? Оно в красивой рамочке, в то время как весь остальной код и параметры не обрамлены. Та же фигня повторяется ещё пару раз ниже по тексту.

    Описание возвращаемого значения функцией.
    Может, «описание возвращаемого функцией значения»? :)

    оно понимает LaTeX формулы и выражения
    «Формулы и выражения LaTeX»!

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

    ОтветитьУдалить
  2. @Minoru комментирует...

    Надо бы таки осилить этот вот Doxygen — судя по твоим заметкам, таки полезная штука
    Осиливать его очень просто, на самом деле. Запускаешь Gnu/Octave, в Kate/Gedit/vim пишешь скрипт, в котором делаешь какие-нибудь расчёты. Пишешь документацию, как я тут привёл примеры (можно прямо скопипастить и поправить). Применяешь перловый скрипт. Всё.

    Doxygen это ОЧЕНЬ полезная система: в моём симуляторе телескопа без подробной документации пользователь застрелится.


    Интересно, а что с текстом «@param arg1 Описание параметра»?
    Хрен его знает: в редакторе он другим шрифтом. Это я его в Опере в Университете правил. Поправлено.

    Может, «описание возвращаемого функцией значения»? :)
    Это лучше, в самом деле.

    «Формулы и выражения LaTeX»!
    Пофиксено.

    Зачем здесь запятая перед «можно»?
    Ты намекаешь, что я уже и пунктуацию забывать начал? :-) Исправил.

    Саш, спасибо за полезные правки! Мне тебя иногда так не хватает, когда я посты пишу (вот прямо сейчас, по секрету, почти закончил ОГРОМНЫЙ постище - в следующем году заготавливай попкорн).

    ОтветитьУдалить