Генерация документации с помощью Doxygen к программам MATLAB

Doxygen это кроссплатформенная система документирования исходных текстов - то есть, пишем в коде нашей программы комментарии в стандартизированной форме, скармливаем это Doxygen и на выходе имеем документацию по использованию нашей программы. Doxygen, разумеется, ни в коем разе не отменяет написание нормальной документации к программам, однако поможет быстро вспомнить вам, что делает написанная вами программа до Грюнвальдской битвы. И использовать это чудо можно не только для С/C++, но даже для программ на MATLAB, для чего есть описываемый далее небольшой перловый костылик.


Doxygen в MATLAB: интродукция
Так как напрямую MATLAB в Doxygen не поддерживается, нужно использовать перловый скрипт, который вытащит комментарии в формате, понятные Doxygen. То есть при вызове doxygen, перловый скрипт на лету переводит комментарии в формат а-ля-C++ и скармливает это Doxygen, который, думая, что это С++, генерит документацию к программе в HTML и LaTeX. При этом комментарии должны начинаться с %> для того, чтобы скрипт смог их обработать и передать Doxygen.

Скрпит разработан замечательным товарищем Фабрисом и выложен на MathWorks, откуда скрипт можно невозбранно скачать вместе с инструкцией по установке (острожно, автор работает под виндой).

Установка и настройка скрипта для использования Doxygen в MATLAB:
Для начала устанавливаем Doxygen штатными средствами вашего дистрибутива. Для Debian это естественно:

aptitude install doxygen doxygen-gui

Последний пакет содержит готичного вида Wizard, который поможет нам настраивать параметры выдачи документации в графическом режиме (что иногда удобнее, чем ортодоксальные vim/emacs/mcedit/whatever).

После установки Doxygen (MATLAB/Octave предполагаются уже установленными) идём на MathWorks за свежей версией архива со скриптом, скачиваем скрипт, и распаковываем. Инструкция по установке очень проста:

• скопировать файл Doxyfile в каталог, где лежат ваши скрипты MATLAB (в моём примере это /home/dot/matlab/projectCoherency где идёт разработка моих MATLAB скриптов по текущему проекту)
• скопировать файл m2cpp.pl в каталог, где лежат ваши скрипты MATLAB.
  

Главный запевала в деле автоматической генерации документации - конфигурационный файл Doxyfile, который придётся править (хотя и незначительно) для каждого крупного проекта (если вы храните MATLAB-скрипты в отдельных каталогах для каждого проекта). Файл m2cpp.pl будет вытаскивать из наших M-файлов комментарии и перегонять их в формат HTML/LATEX/RTF.

Редактируем файл Doxyfile с помощью vim/emacs/mcedit/к_чему_вы_там_прикипели_ или командой doxywizard Doxyfile для того, чтобы изменить следующие настройки:

• PROJECT_NAME = Coherence
  
• FILTER_PATTERNS = *.m=./m2cpp.pl
• OUTPUT_DIRECTORY = ./Doc/
• INPUT = .
• PERL_PATH = /usr/bin/perl
• STRIP_FROM_PATH = .

Обращаю внимание: OUTPUT_DIRECTORY это тот каталог, где теперь будет лежать ваша документация - в моём случае это подкаталог ./Doc/

Это основные настройки, которые дадут вам приемлемый результат. Настроек очень много и с ними можно играться довольно долго. На всякий случай выкладываю свой Doxyfile:

--------------------- НАЧАЛО ФАЙЛА ------------------------
# Doxyfile 1.5.6

#---------------------------------------------------------------------------
# Project related configuration options
#---------------------------------------------------------------------------
DOXYFILE_ENCODING = UTF-8
PROJECT_NAME = Coherence
PROJECT_NUMBER =
OUTPUT_DIRECTORY = ./Doc/
CREATE_SUBDIRS = YES
OUTPUT_LANGUAGE = English
BRIEF_MEMBER_DESC = NO
REPEAT_BRIEF = YES
ABBREVIATE_BRIEF = "The $name class" \
"The $name widget" \
"The $name file" \
is \
provides \
specifies \
contains \
represents \
a \
an \
the
ALWAYS_DETAILED_SEC = YES
INLINE_INHERITED_MEMB = YES
FULL_PATH_NAMES = NO
STRIP_FROM_PATH = ./
STRIP_FROM_INC_PATH =
SHORT_NAMES = NO
JAVADOC_AUTOBRIEF = YES
QT_AUTOBRIEF = NO
MULTILINE_CPP_IS_BRIEF = NO
DETAILS_AT_TOP = NO
INHERIT_DOCS = YES
SEPARATE_MEMBER_PAGES = NO
TAB_SIZE = 16
ALIASES =
OPTIMIZE_OUTPUT_FOR_C = NO
OPTIMIZE_OUTPUT_JAVA = NO
OPTIMIZE_FOR_FORTRAN = NO
OPTIMIZE_OUTPUT_VHDL = NO
BUILTIN_STL_SUPPORT = NO
CPP_CLI_SUPPORT = YES
SIP_SUPPORT = NO
IDL_PROPERTY_SUPPORT = YES
DISTRIBUTE_GROUP_DOC = NO
SUBGROUPING = YES
TYPEDEF_HIDES_STRUCT = YES
#---------------------------------------------------------------------------
# Build related configuration options
#---------------------------------------------------------------------------
EXTRACT_ALL = YES
EXTRACT_PRIVATE = YES
EXTRACT_STATIC = YES
EXTRACT_LOCAL_CLASSES = YES
EXTRACT_LOCAL_METHODS = YES
EXTRACT_ANON_NSPACES = YES
HIDE_UNDOC_MEMBERS = NO
HIDE_UNDOC_CLASSES = NO
HIDE_FRIEND_COMPOUNDS = NO
HIDE_IN_BODY_DOCS = NO
INTERNAL_DOCS = YES
CASE_SENSE_NAMES = NO
HIDE_SCOPE_NAMES = YES
SHOW_INCLUDE_FILES = YES
INLINE_INFO = YES
SORT_MEMBER_DOCS = YES
SORT_BRIEF_DOCS = NO
SORT_GROUP_NAMES = NO
SORT_BY_SCOPE_NAME = NO
GENERATE_TODOLIST = YES
GENERATE_TESTLIST = YES
GENERATE_BUGLIST = YES
GENERATE_DEPRECATEDLIST= YES
ENABLED_SECTIONS =
MAX_INITIALIZER_LINES = 30
SHOW_USED_FILES = YES
SHOW_DIRECTORIES = YES
SHOW_FILES = YES
SHOW_NAMESPACES = YES
FILE_VERSION_FILTER =
#---------------------------------------------------------------------------
# configuration options related to warning and progress messages
#---------------------------------------------------------------------------
QUIET = YES
WARNINGS = YES
WARN_IF_UNDOCUMENTED = YES
WARN_IF_DOC_ERROR = YES
WARN_NO_PARAMDOC = YES
WARN_FORMAT = "$file:$line: $text"
WARN_LOGFILE =
#---------------------------------------------------------------------------
# configuration options related to the input files
#---------------------------------------------------------------------------
INPUT = ./
INPUT_ENCODING = ISO-8859-1
FILE_PATTERNS = *.c \
*.cc \
*.cxx \
*.cpp \
*.c++ \
*.d \
*.java \
*.ii \
*.ixx \
*.ipp \
*.i++ \
*.inl \
*.h \
*.hh \
*.hxx \
*.hpp \
*.h++ \
*.idl \
*.odl \
*.cs \
*.php \
*.php3 \
*.inc \
*.m \
*.mm \
*.dox \
*.py \
*.f90 \
*.f \
*.vhd \
*.vhdl
RECURSIVE = YES
EXCLUDE = ./.hg/
EXCLUDE_SYMLINKS = YES
EXCLUDE_PATTERNS = *.py
EXCLUDE_SYMBOLS =
EXAMPLE_PATH =
EXAMPLE_PATTERNS = *
EXAMPLE_RECURSIVE = NO
IMAGE_PATH =
INPUT_FILTER =
FILTER_PATTERNS = *.m=./m2cpp.pl
FILTER_SOURCE_FILES = NO
#---------------------------------------------------------------------------
# configuration options related to source browsing
#---------------------------------------------------------------------------
SOURCE_BROWSER = YES
INLINE_SOURCES = NO
STRIP_CODE_COMMENTS = YES
REFERENCED_BY_RELATION = YES
REFERENCES_RELATION = YES
REFERENCES_LINK_SOURCE = YES
USE_HTAGS = NO
VERBATIM_HEADERS = YES
#---------------------------------------------------------------------------
# configuration options related to the alphabetical class index
#---------------------------------------------------------------------------
ALPHABETICAL_INDEX = YES
COLS_IN_ALPHA_INDEX = 5
IGNORE_PREFIX =
#---------------------------------------------------------------------------
# configuration options related to the HTML output
#---------------------------------------------------------------------------
GENERATE_HTML = YES
HTML_OUTPUT = html
HTML_FILE_EXTENSION = .html
HTML_HEADER =
HTML_FOOTER =
HTML_STYLESHEET =
HTML_ALIGN_MEMBERS = YES
GENERATE_HTMLHELP = NO
GENERATE_DOCSET = NO
DOCSET_FEEDNAME = "Doxygen generated docs"
DOCSET_BUNDLE_ID =
HTML_DYNAMIC_SECTIONS = NO
CHM_FILE =
HHC_LOCATION =
GENERATE_CHI = NO
CHM_INDEX_ENCODING =
BINARY_TOC = NO
TOC_EXPAND = YES
DISABLE_INDEX = NO
ENUM_VALUES_PER_LINE = 4
GENERATE_TREEVIEW = ALL
TREEVIEW_WIDTH = 250
FORMULA_FONTSIZE = 10
#---------------------------------------------------------------------------
# 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
#---------------------------------------------------------------------------
# configuration options related to the RTF output
#---------------------------------------------------------------------------
GENERATE_RTF = NO
RTF_OUTPUT = rtf
COMPACT_RTF = NO
RTF_HYPERLINKS = NO
RTF_STYLESHEET_FILE =
RTF_EXTENSIONS_FILE =
#---------------------------------------------------------------------------
# configuration options related to the man page output
#---------------------------------------------------------------------------
GENERATE_MAN = NO
MAN_OUTPUT = man
MAN_EXTENSION = .3
MAN_LINKS = NO
#---------------------------------------------------------------------------
# configuration options related to the XML output
#---------------------------------------------------------------------------
GENERATE_XML = NO
XML_OUTPUT = xml
XML_SCHEMA =
XML_DTD =
XML_PROGRAMLISTING = YES
#---------------------------------------------------------------------------
# configuration options for the AutoGen Definitions output
#---------------------------------------------------------------------------
GENERATE_AUTOGEN_DEF = NO
#---------------------------------------------------------------------------
# configuration options related to the Perl module output
#---------------------------------------------------------------------------
GENERATE_PERLMOD = NO
PERLMOD_LATEX = NO
PERLMOD_PRETTY = YES
PERLMOD_MAKEVAR_PREFIX =
#---------------------------------------------------------------------------
# Configuration options related to the preprocessor
#---------------------------------------------------------------------------
ENABLE_PREPROCESSING = YES
MACRO_EXPANSION = NO
EXPAND_ONLY_PREDEF = NO
SEARCH_INCLUDES = YES
INCLUDE_PATH =
INCLUDE_FILE_PATTERNS =
PREDEFINED =
EXPAND_AS_DEFINED =
SKIP_FUNCTION_MACROS = YES
#---------------------------------------------------------------------------
# Configuration::additions related to external references
#---------------------------------------------------------------------------
TAGFILES =
GENERATE_TAGFILE =
ALLEXTERNALS = NO
EXTERNAL_GROUPS = YES
PERL_PATH = /usr/bin/perl
#---------------------------------------------------------------------------
# Configuration options related to the dot tool
#---------------------------------------------------------------------------
CLASS_DIAGRAMS = NO
MSCGEN_PATH =
HIDE_UNDOC_RELATIONS = NO
HAVE_DOT = NO
DOT_FONTNAME = FreeSans
DOT_FONTPATH =
CLASS_GRAPH = YES
COLLABORATION_GRAPH = YES
GROUP_GRAPHS = YES
UML_LOOK = NO
TEMPLATE_RELATIONS = NO
INCLUDE_GRAPH = YES
INCLUDED_BY_GRAPH = YES
CALL_GRAPH = YES
CALLER_GRAPH = YES
GRAPHICAL_HIERARCHY = YES
DIRECTORY_GRAPH = YES
DOT_IMAGE_FORMAT = png
DOT_PATH = /usr/bin/
DOTFILE_DIRS =
DOT_GRAPH_MAX_NODES = 54
MAX_DOT_GRAPH_DEPTH = 0
DOT_TRANSPARENT = NO
DOT_MULTI_TARGETS = NO
GENERATE_LEGEND = YES
DOT_CLEANUP = YES
#---------------------------------------------------------------------------
# Configuration::additions related to the search engine
#---------------------------------------------------------------------------
SEARCHENGINE = NO
--------------------- КОНЕЦ ФАЙЛА ------------------------

После этого переходим в корень проекта (в моём случае это /home/dot/matlab/projectCoherency) и пишем:

$ doxygen Doxyfile

Программа может работать довольно долго, особенно если в коде очень много формул. Далее в посте приводится два примера моих небезуспешных попыток заставить всё это работать.


Комментирование кода скриптов в MATLAB с учётом Doxygen
В общих чертах комментарии к коду MATLAB представляют собой краткое описание того, что реализует скрипт. После перечисления известных ошибок (@bug) и дополнительных работ (@todo) желательно составить из текста комментариев непосредственно кода (переменных, ответственных блоков скрипта) расширенное описание алгоритма (чтобы потом не тратить полдня на выяснение того, что же это, собственно, тут происходит в программе).
Вот как это выглядит в программе (далее - кусок MATLAB-скрипта с раскраской а-ля-Kate):

%> @file kmvFittingData.m
%> @brief This MATLAB script is a part of my study of Linear Least Squares estimation. The goal here is to solve classical problem: fitting a line on experimental data. For instance, we have many experimental points and we need to approximate them by a line.
%>%> @author Mikhail V. Konnik
%> @date   11 May 2010
%> @bug    No known bugs.
%> @todo The following features must be implemented:
%> - MMSE
%> - Asymptotic Standard Error calculation
%>
%> @section fitintro Fitting the data
%> Least Squares Fitting is a mathematical procedure for finding the best-fitting curve to a given set of points by minimising the sum of the squares of the offsets ("the residuals") of the points from the curve. The problem here is a classical one: fit a line into experimental dots. For the sake of study we assume the 2-D case and solve it.
%> The general case is \f$A\hat{x} = b\f$, where \f$\hat{x}\f$ is an @b estimator of true x - since there is no solution here, we need to minimise the error \f$||Ax - b||^2\f$.
%>
%> @subsection fitmodel Ordinary Least Squares Estimation for data fitting
%> First part of program is Ordinary Least squares approximation of provided data.
%> @attention The linear model here is \f$y=a\cdot X+b\f$; the data is in format \f$\{y_i;x_i\}\f$.%> %> The square here \f$||Ax - b||^2\f$ is a very important since the error may be positive or negative, so we need to minimise exactly @b square.%>%> The answer is to actually project the vector b onto \f$Ax\f$ plane with minimal distance - that is exactly a orthogonal projection: \f$A^TA\hat{x} = A^Tb\f$. From that we immediately have the least squares solution: \f$\hat{x} = (A^TA)^{-1}A^Tb\f$. Note this is a Ordinary Least Square Estimation (OLSE) of x and the \f$\hat{x}\f$ is linear @b estimator of x.%>%> See @ref fitintro if you want more details about Linear Least Squares details.%>%> For the information about statistical characteristics of Goodness of Fit, see @ref kmvgof for the details about kmvgof.m function.%>%> @subsection levenbergmarquartd Numerical solve of OLS: Levenberg-Marquardt algorithm%> The Levenberg--Marquardt algorithm (LMA) provides a numerical solution to the problem of minimizing a function, generally nonlinear, over a space of parameters of the function. These minimization problems arise especially in least squares curve fitting and nonlinear programming.%> The LMA interpolates between the Gauss--Newton algorithm (GNA) and the method of gradient descent. The LMA is more robust than the GNA, which means that in many cases it finds a solution even if it starts very far off the final minimum. On the other hand, for well-behaved functions and reasonable starting parameters, the LMA tends to be a bit slower than the GNA. LMA can also be viewed as GNA improved with trust region approach.%> The LMA is a very popular curve-fitting algorithm used in many software applications for solving generic curve-fitting problems.% ==============================================================================datavector = [1,2,3;1,2,2]'; %> the vector that contains experimental data%%%%%%%%
<----------- Least squares approximation PART -------------- #####
datafit_b = datavector(:,2); %% vector b (or y in y=ax+b model)
datafit_A = zeros(size(datavector));  %% fill in the matrix of coefficients from the initial data vector
datafit_A(:,1) = datavector(:,1);

То есть описание программы идёт первым делом (и оно-то и будет преобразовано в документацию), а дальше описание переменных и блоков (этого в документации, к сожалению, не будет, но нужно всё равно).

Здесь главное - не прерывать раздел комментариев и вставлять %> в каждую пустую строчку, иначе Doxygen будет игнорировать любые строки комментариев после первого обрыва %>

А вот что получилось при перегоне в HTML:

kmvFittingData.m File Reference

This MATLAB script is a part of my study of Linear Least Squares estimation. More...
Go to the source code of this file.

---

Detailed Description

This MATLAB script is a part of my study of Linear Least Squares estimation.
The goal here is to solve classical problem: fitting a line on experimental data. For instance, we have many experimental points and we need to approximate them by a line.

Author:

Mikhail V. Konnik

Date:

11 May 2010

Bug:

No known bugs.

Todo:

The following features must be implemented:

• MMSE
• Asymptotic Standard Error calculation

Fitting the data

Least Squares Fitting is a mathematical procedure for finding the best-fitting curve to a given set of points by minimising the sum of the squares of the offsets ("the residuals") of the points from the curve. The problem here is a classical one: fit a line into experimental dots. For the sake of study we assume the 2-D case and solve it. The general case is , where is an estimator of true x - since there is no solution here, we need to minimise the error .

Маленькое примечание: формулы здесь приведены в виде кода, но на самом деле они сгенерированы как картинки в HTML. В документе LaTeX они выглядят как нормальные формулы.

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

%> @file kmvComplCorrRndDataGenerator_func.m
%> @brief This routine does the generation of complex correlated data. Only complex covariation matrix is used. The generation of the complex correlated random data is performed by Cholseky decomposition of the covariation matrix \f$ \Sigma = C\cdot C^H \f$ that is C = chol(A).
%>
%> @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
%> - find the programs that uses incorrect references of row vectors (instead of columns)
%> - correct the other programs that uses incorrect references of row vectors (instead of columns)
%>
%> @section randchol Cholesky decomposition and Generation of Correlated Random Variables
%> In order to start the study of random variables and theis correlation matrices, we need to generate the random variables/matrices with given variance/covariance matrix.
% ======================================================================
%> @brief Generator of correlated complex random variables from Normal random process.
%>
%> @c The @c algorithm:
%>  - factoring of the matrix to Cholesky factorization \f$ C\cdot C^H= \Sigma \f$
%>  - generate kmvZ preliminary random samples \f$ Z \f$
%>  - cooking the random vectors X with desired correlation matrix kmvSigma: \f$X=C^H \cdot Z\f$
%>
%> @param arg1 Covariation matrix (square, symmetric, with real diagonal)
%> @param arg2 Desirable length of the random vectors
%> @param arg3 [optional] is verbose then show the covariation matrix
%>
%> @retval kmvXRandomProcess return random vectors X with desired correlation matrix kmvSigma
% ======================================================================

Собственно, сначала функция описывается так же, как и скрипт. Далее непосредственно перед кодом функции описываем её переменные с помощью тега @param и возвращаемые переменные с помощью тега @retval

Вот как всё это выглядит в HTML:

kmvComplCorrRndDataGenerator_func.m File Reference

This routine does the generation of complex correlated data. More...
Go to the source code of this file.

Typedefs
typedef void *	in
Functions
function	kmvXRandom (in varargin)

---

Detailed Description

This routine does the generation of complex correlated data.
Only complex covariation matrix is used. The generation of the complex correlated random data is performed by Cholseky decomposition of the covariation matrix that is C = chol(A).

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
• find the programs that uses incorrect references of row vectors (instead of columns)
• correct the other programs that uses incorrect references of row vectors (instead of columns)

Cholesky decomposition and Generation of Correlated Random Variables

In order to start the study of random variables and theis correlation 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.
Definition in file kmvComplCorrRndDataGenerator_func.m.

---

Typedef Documentation

typedef void* in

Definition at line 1 of file kmvComplCorrRndDataGenerator_func.m.

---

Function Documentation

function kmvXRandom

(

in

varargin

)

Generator of correlated complex random variables from Normal random process.
The algorithm:

• factoring of the matrix to Cholesky factorization
• generate kmvZ preliminary random samples
• cooking the random vectors X with desired correlation matrix kmvSigma:

Parameters:

	arg1	Covariation matrix (square, symmetric, with real diagonal)
	arg2	Desirable length of the random vectors
	arg3	[optional] is verbose then show the covariation matrix

Return values:

kmvXRandomProcess

return random vectors X with desired correlation matrix kmvSigma

При этом важно не разрывать блок комментариев - каждая новая строка, которая будет обрабатываться Doxygen, должна начинаться с %> Таково устройство скрипта, который переводит все комментарии, начинающиеся с %> в комментарии С++, понятные Doxygen.

Эти два примера в общем дают достаточное представление о том, как можно использовать Doxygen для генерации документации к скриптам MATLAB.

Ссылки на тему:
Для быстрого старта работы с Doxygen есть хорошая страничка от IBM, рекомендации по комментированию, и использование LaTeX с Doxygen. Также есть довольно толковое руководство, правда, больше по С\С++ и совершенно замечательная шпаргалка.