如何记录面向对象的MATLAB代码？

Question

我正在使用面向对象的MATLAB编写一个相当大的应用程序,这让我想到了如何记录代码.如果这是C,我会使用Doxygen.对于Java,我使用JavaDoc.两者都主要就类和方法文档的外观和应包含的内容达成一致的标准.

但是MATLAB代码怎么样？我在TMW自己的类中看到的最多的是在本课程顶部的一两句话,我找不到任何专门用于记录大型MATLAB应用程序的主题.

那么如何记录您的MATLAB类？任何特定的样式问题或其他工具？

Answer 1

我意识到问题是陈旧的,但为了Google的利益:Matlab有一个内置的功能.您以某种样式(JavaDoc)编写注释,并通过help和doc函数获取它们.它可用于记录类,属性和方法.它令人惊讶的完整,但有点挑剔.该文件在这里:

http://www.mathworks.com/help/matlab/creating-help.html

Answer 2

我通过以下方式记录我的oo代码:

1. 在包含'classdef'的文件的开头,我写了一个类的内容和典型用法的摘要.我还详细解释了属性,并为每个方法添加了1个句子的描述.
2. 在每个属性定义之后,我添加一个关于它的解释性句子(在同一行)
3. 每个方法都记录为一个函数,即它有一个H1行,一个概要,以及输入和输出参数的解释.

当你调用'doc myClass'时,你会在开头看到(1),然后是你在(2)中添加的句子所解释的属性列表,以及显示H1行和其余部分的方法列表.如果你点击链接,请帮助(3).

此外,我的所有类都是一个通用超类的子类,它实现了(以及其他)调用doc(class(obj))的方法'help',这允许我从类的每个实例中提取帮助.

例

%# 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相同的摘要,或者您使用内置文档浏览器获得的摘要.

Answer 3

尝试使用matlabdomain扩展的Sphinx。Sphinx 是一个Python包，它使用ReStructuredText (rst) 标记自动记录代码。扩展 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、latex 等），如本博客文章中所示。