Генерация документации с помощью 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 $A\hat{x} = b$, where $\hat{x}$ is an estimator of true x - since there is no solution here, we need to minimise the error $||Ax - b||^2$.

Маленькое примечание: формулы здесь приведены в виде кода, но на самом деле они сгенерированы как картинки в 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 $ \Sigma = C\cdot C^H $ 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 $ C\cdot C^H= \Sigma $
  • generate kmvZ preliminary random samples $ Z $
  • cooking the random vectors X with desired correlation matrix kmvSigma: $X=C^H \cdot Z$
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. Также есть довольно толковое руководство, правда, больше по С\С++ и совершенно замечательная шпаргалка.

15 комментариев: |высказаться!| RSS-лента дискуссии.|
Анонимный комментирует...

Очень благодарен за статью всегда читаю вас с удовольствием и спасибо что можно читать ваши статьи через жж очень удобно ))

virens комментирует...

@Анонимный комментирует...
Очень благодарен за статью
Пожалуйста. На самом деле это, конечно, костыль, но мне он очень нравится - есть возможность использовать Doxygen. Собственно, я так пишу документацию к своему симулятору на матлабе.

Статья выглядит до некоторой степени слонобойно (и на подходе вторая часть), но на самом деле её написание позволило мне собрать в кучку все свои немногочисленные познания по Doxygen. Авось кому пригодится.

можно читать ваши статьи через жж очень удобно
Отвлекаясь от темы поста - я не знаю, кто для меня сделал syndicaton, но надеюсь, что оно полезно. Так как у меня ЖЖ нет, есть вопрос: если трансляцию в ЖЖ можно как-то улучшить, просьба писать сюда не стесняясь (желательно вместе с решением).

Сергей комментирует...

А ещё можно почти на любом языке программирования писать «литературный код» с помощью noweb. Для этого (обычно именованные) блоки кода надо начинать с

<<имя блока>&gt=

и заканчивать знаком @ и переводом строки или пробелом. А между ними писать человеческий текст, используя любимый язык разметки, хоть HTML, хоть LaTeX.

Программкой noweave из этого исходника можно сделать документацию, а программкой notangle — извлекать блоки кода.

Пример литературного кода, и получающая из него документация.

virens комментирует...

@Сергей комментирует...
А ещё можно почти на любом языке программирования писать «литературный код» с помощью noweb.
Забавно, но это не то, что мне нужно. Моя документация находится внутри программы и является частью исполняемых скриптов. То есть для получения документации не надо разделять комменты и код - это одно целое.

Но за ссылку мерси, буду знать.

Minoru комментирует...

Вау! Давненько уже хотел взглянуть на Doxygen чуть поближе, но всё руки не доходили. Теперь имею хоть какое-то представление, что оно такое. Мне оно, вобщем-то, пока что не нужно, но мало ли…

Ну-с, перейдём к хит-параду оплошностей (:

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

> Рабочий пример документации, сгенерированной Doxygen описанным способом, из кода программ на MATLAB в исследовательском продакшене можно ознакомиться здесь.
Что-то ты совсем русский забывать стал, virens… И да, ссылка ведёт на пустую страницу (в смысле, никаких примеров там и в помине нет).

Блоки для кода у тебя странные — никаких тебе переносов или скроллбаров, если контент не помещается. Надо бы починить.

> Так же есть довольно толковое руководство
Традиции, традиции… :)

virens комментирует...

@Minoru комментирует...
Это он, это он, моего сердца чемпион! :-)

Давненько уже хотел взглянуть на Doxygen чуть поближе
Аптитьюд инстулл доксиджен --ХОТЕТЬ! :-))
И всё сделано.

Теперь имею хоть какое-то представление, что оно такое.
Мне надо было что-то для комментирования кода и генерации документации автоматом. Серж выше пропиарил литературное программирование, но оно требует конвертации. А это в одном флаконе.

Здесь ты, по-моему, сбился с мысли, так что сто́ит перечитать и написать правильно ;)
Ох ну ты граммар-гауляйтер после этого (ударения на стоит). :-) И да, с мысли я сбился. Я этот пост долго писал, а потом дополнял, а потом разбивал на два (вторая серия с погоней, перестрелкой и голыми женщинами скоро будет).
Исправил.

Что-то ты совсем русский забывать стал, virens..
Ит из нот супрзайзинг синс ай лив вери фар эвэй ин зе ленд оф крокодайлз анд кангуруэз :-)
Снёс тот абзац к едрене фене.

И да, ссылка ведёт на пустую страницу (в смысле, никаких примеров там и в помине нет).
Снёс я их оттуда после набега китайских охотников до халявы.

Блоки для кода у тебя странные — никаких тебе переносов или скроллбаров, если контент не помещается.
Блоки эти мне всю плешь съели. Это копипаста из HTML-файла, а как сделать перенос, я не в теме.

Надо бы починить.
Это я вот как раз и не знаю, как сделать.

> Так же есть довольно толковое руководство
Традиции, традиции... :)

Гауляйтер, ты безжалостен: я думал, что Минору посмотрит на размер поста и скажет "да ну нафиг". Но истинный ариец таки нашёл... мою верность традициямЪ :-)

P.S. правило с грамоты.ру ещё не вкуривал.

Dr.AKULAvich комментирует...

Мимо проходил :-)
По теме высказать нечего, буду вопрос ребром ставить. virens, зачем код в тегах для цитат держать?

Чтобы скролились строки попробуй вместо blockquote обернуть блок тегом pre примерно так:
[pre style="overflow:auto;"]

virens комментирует...

@Dr.AKULAvich комментирует...
Мимо проходил :-)
Ты заходи, если что (С) :-)

вопрос ребром ставить. virens, зачем код в тегах для цитат держать?
Не распарсил. Имеешь в виду, зачем я выдал сюда латеховский код? Если да - чтоб искать потом было удобно.

Чтобы скролились строки попробуй вместо blockquote обернуть блок тегом pre примерно так
Что-то не помогло оно. Шаблон рубит quotation по ширине (там всё в пикселях, чтоб его).

В общем, из поста должно сложиться некое представление о том, зачем оно надо. Надеюсь, оно отчасти сложилось.

Dr.AKULAvich комментирует...

> кусок MATLAB-скрипта с раскраской а-ля-Kate
Далее в теге blockquote наблюдаем обрезанные строки. Я имел ввиду, что для вставки листингов лучше использовать свой блок, а не цитирование. У меня, к примеру, в CSS прописаны правила для класса pre "listing", так выглядит код в блоге.

virens комментирует...

@Dr.AKULAvich комментирует...
У меня, к примеру, в CSS прописаны правила для класса pre "listing", так выглядит код в блоге.
Круто выглядит у тебя в блоге :-) Слышь, Тартилла, продай тайну Золотого ключика, не? :-)

Dr.AKULAvich комментирует...

А тайна сия кроется под волнами шелестящими, написал в Google Wave.

virens комментирует...

@Dr.AKULAvich комментирует...
А тайна сия кроется под волнами шелестящими
Спасибо тебе, хороший человек Акулович!
Заимплементил я сие инновационное мысли чудо, и зело краше стало отображенье кода бусурманского, а страница стараньями твоими стала ещё вебдванолистее, прогрессивнее и молодёжнее.
Старик Виренс шапку ломает в благоговейном почёте пред знатоком цеэсэсов и аштемеелей :-)

Dr.AKULAvich комментирует...

Всегда пожалуйста. «Знаток», громко сказано, решал похожие проблемы с отображением, гугл указал, куда копать :-)

Есть подозрение, что в первом листинге пятая снизу строка шибко длинная, видимо, сбилось форматирование.

P. S. Гугл серьёзно улучшил фильтр спам-комментариев, я на радостях отключил у себя капчу. Никаких проблем пока не наблюдаю.

Анонимный комментирует...

Кстати, о дизайне. http://imgur.com/j6Ihx.png

virens комментирует...

@Dr.AKULAvich комментирует...
«Знаток», громко сказано, решал похожие проблемы с отображением, гугл указал, куда копать :-)
Главное, что поделился рецептом. Я этот твой пост прозевал.

P.S. Гугл серьёзно улучшил фильтр спам-комментариев
Это точно.

я на радостях отключил у себя капчу. Никаких проблем пока не наблюдаю.
Я тоже, оставил только премодерацию после 5 дней. Думал, что народ больше комментировать будет, но пока вроде столько же. Или может лето, все уехали...


@Анонимный комментирует...
Кстати, о дизайне. http://imgur.com/j6Ihx.png
Так получилось, Анонимус. Кстати, это подтолкнуло автора несколько подпилить шаблон, должно стать лучше.

Отправить комментарий

Подписаться на RSS-ленту комментариев к этому посту.