Как документировать объектно-ориентированный код MATLAB?

Я документирую код своего кода следующим образом:

• В начале файла, содержащего "classdef", я пишу сводку того, что делает класс, и типичное использование. Я также подробно объясняю свойства и добавляю описание каждого предложения из 1 предложения.
• После каждого определения свойства я добавляю к нему одно объяснительное предложение (в той же строке)
• Каждый метод документируется как функция, то есть имеет H1-строку, синопсис и объяснение входных и выходных параметров.

Когда вы вызываете "doc myClass", вы увидите (1) в начале, а затем список свойств, объясняемых предложениями, добавленными в (2), и списком методов, которые показывают строку H1 и остальную часть справки (3), если вы нажмете на ссылку.

Кроме того, все мои классы подкласса имеют общий суперкласс, который реализует (среди прочего) метод "help", который вызывает doc (class (obj)), что позволяет мне вызывать помощь из каждого экземпляра класса.

Пример

%# MYCLASS is a sample class
%# All this text will show up at the top of the help if you call 'doc myClassName'
%#
%# myClass is an example for documentation. It implements the following properties and methods:
%# PROPERTIES
%#    myProp - empty sample property (some more explanation could follow here)
%#
%# METHODS
%#    myMethod - sample method that calls doc
%#

classdef myClass

properties
    myProp = []; %# empty sample property
end %# properties

methods

%%# MYMETHOD -- use %% so that you can easily navigate your class file
function myMethod(obj)
%#MYMETHOD calls up the help for the object
%#
%# SYNOPSIS myMethod(obj)
%# INPUT obj: the object
%# OUTPUT none
%#
   try
      doc(class(obj))
   catch
      help(class(obj))
   end
   end %#myMethod
end %#methods

end %#myClass

Изменить 1 Если вам нужна хорошая html-документация, вы можете, кроме того, использовать m2html для сгенерируйте его для вас. M2html будет собирать тексты справки, и он может даже делать графики зависимостей.

Редактировать 2 В то время как m2html документирует стандартный код Matlab, он не имеет конкретной поддержки для классов. Это означает, что вы получаете методы как "подфункции", связанные в классе, но вы не получите столь же краткий обзор, как и с Doxygen, или который вы получаете со встроенным браузером документации.

Попробуйте Sphinx с matlabdomain расширение. Sphinx - это Python пакет, который автоматически записывает код с помощью ReStructuredText (первый ) разметки. Расширение sphinxcontrib-matlabdomain позволяет автоматически документировать код MATLAB, который использует первую разметку, распознанную Sphinx в своих докстронгах. Отправляйте ошибки и предложения в отслеживатель ошибок на BitBucket.

Например, следующий код в my_project/my_fun.m:

function [outputs] = my_fun(args)
% MY_FUN does really cool stuff
% [OUTPUTS] = MY_FUN(ARGS)
%
% :param args: Input arguments
% :type args: cell array
% :returns: outputs
% :raises: :exc:`my_project.InvalidInput`

code ...
end

будет задокументирован в первом файле следующим образом:

.. _my-project

My Project
==========
.. automodule:: my_project

    This folder contains all the functions and classes for my project.

My Function
-----------
.. autofunction:: my_fun

и создаст html (или pdf, латекс и многие другие), как то, что показано на этом сообщении в блоге.

В FileExchange существует Doxygen-адаптер для M файлов, см. http://www.mathworks.com/matlabcentral/fileexchange/25925-using-doxygen-with-matlab.