MATLAB m文件帮助格式

试试官方文档中的其他部分。更彻底。MATLAB>“用户指南”>“桌面工具和开发环境”>“自定义帮助和演示”>“提供您自己的帮助和演示”。这描述了简单的helptext和生成单独的HTML帮助文件。

这是我收集到的帮助文本格式,并发现有用。

function foo(x,y,z)
%FOO One-line description goes here
%
% foo(x,y,z)
%
% Multi-line paragraphs of descriptive text go here. It's fine for them to
% span lines. It's treated as preformatted text; help() and doc() will not
% re-wrap lines. In the editor, you can highlight paragraphs, right-click,
% and choose "Wrap selected comments" to re-flow the text.
%
% More detailed help is in the <a href="matlab: help foo>extended_help">extended help</a>.
% It's broken out like this so you can keep the main "help foo" text on 
% a single screen, and then break out obscure parts to separate sections.
%
% Examples:
% foo(1,2,3)
%
% See also:
% BAR
% SOMECLASS/SOMEMETHOD

disp(x+y+z);

function extended_help
%EXTENDED_HELP Some additional technical details and examples
%
% Here is where you would put additional examples, technical discussions,
% documentation on obscure features and options, and so on.

error('This is a placeholder function just for helptext');

• 函数签名后的第一行称为“H1行”。它只需要一行,这样contentsrpt()就可以正确地提取它,它可以从函数中的helptext自动生成Contents.m文件
• H1行中的函数名都是大写,而不管签名中函数名的实际大小写
• “See also:”后面的函数名都是大写。方法名是限定的;我认为与当前方法在同一个类中的方法的名称可以是非限定的。

H1行和“Examples:”之间的所有内容都是我觉得可读的常规格式;help()没有特别处理它。

您可以在“帮助”中使用有限形式的超链接。特别是,可以使用超链接调用任意Matlab命令,并通过调用help()来指向helptext的其他部分。您可以使用它指向任何函数;“function>subfunction”只是在help()调用中寻址子函数的语法。不幸的是,由于您需要在这些超链接中输入“help”或“doc”,所以它只能在一种或另一种表示形式中起作用。如果有一个直接的helptext超链接表单会更好。

doc(class(obj))

为了帮助我做到始终如一(并确保我不会忘记一些事情),我创建了一个 automatic function template

function testhelp
%TESTHELP is an example (this is the H1 line)
%
% SYNOPSIS: a=testhelp(b,c)
%
% INPUT b: some input parameter
%       c: (opt) some optional input parameter. Default: []
%
% OUTPUT a: some output parameter
%
% REMARKS This is just an example, it won't run
%
% SEE ALSO testHelpFunction
%
% created with MATLAB ver.: 7.11.0.584 (R2010b) on Mac OS X  Version: 10.6.4 Build: 10F569 
%
% created by: Jonas
% DATE: 01-Oct-2010
%

我想有一些(见示例),但我从来没有找到合适的文档。我经常有这样的障碍:

% ...
%
% See also:
%   this_other_function()
%
% <author>

See also 零件格式为标题,但如果替换 另请参见 因为别的原因,它不起作用。如果有人找到这些支持的标题列表,请链接到这里!

编辑 :

我最近来了解一下matlab的内置发布系统。似乎MATLAB注释支持某种形式的标记,与Markdown的语法不太远(正如在so中使用的一样),它支持LaTeX方程等。

有一篇“罗兰关于MATLAB艺术”的帖子 short introduction 关于发布和标记。有关完整参考,请参见 Making Up MATLAB Comments for Publishing 在Mathworks网站上。

当您的代码准备好后,您可以使用 publish() function

    % Other formats are supported, refer to documentation.
options.format = 'html';

    % I don't evaluate the code, especially for functions that require arguments.
    % However, if providing a demo, turning this on is a fantastic way to embed
    % figures in the resulting document.
options.evalCode = false;

    % You can run this in a loop over files in the currrent directory if desired.
publish('script.m', options);