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代码：

在包含'classdef'的文件的开头，我写了一个类的内容和典型用法的摘要。我还详细解释了属性，并添加了每个方法的1个句子描述。
在每个属性定义之后，我添加一个关于它的解释性句子（在同一行上）
每个方法都记录为一个函数，即它有一个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

使用Sphinx扩展名试试matlabdomain。 Sphinx是一个Python包，使用ReStructuredText (rst) markup自动记录代码。扩展名sphinxcontrib-matlabdomain允许自动记录MATLAB代码，该代码使用Sphinx在其文档字符串中识别的第一个标记。将错误和建议发送到issue tracker on 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等等），如this blog post所示。

Answer 4

FileExchange上存在用于M-Files的Doxygen-Adapter，请参阅http://www.mathworks.com/matlabcentral/fileexchange/25925-using-doxygen-with-matlab。

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

4 个答案: