MATLAB m-file帮助格式化

Question

MATLAB m-file帮助格式化

matlabformatting

23

我找不到可用于编写自己的MATLAB函数帮助文档的格式。在官方文档中几乎没有信息。

你知道有哪些其他格式可以在Help Browser中显示（而不是help函数）吗？因为这是针对内置函数的。如何设置标题格式（例如语法、描述、示例）？是否支持项目符号、表格？或者可能应该是一个单独的文件？

我尝试过类似PUBLISH和HTML的文本标记，但没有成功。

我只找到一件有趣的事情。如果你的函数包含混合大小写，比如testHelpFunction，它的名称会被突出显示：

alt text

如果只是测试testhelpfunction，则不需要高亮显示。

还有其他想法吗？

更新

这里是我找到的关于创建自己的帮助文件的详细文档：

提供您自己的帮助和演示
（死链接已替换为Web存档链接）

（已删除失效链接）

再次更新：

- yuk

你应该将你的更新作为一个答案发布，并接受它！ - Alex Feinman

1

@Alex，我之前的问题意在收集有关m文件格式的信息，创建单独的文档只是一个附带问题。 - yuk

现在这两个链接都失效了... - Alec Jacobson

谢谢，@mangledorf！Mathworks居然不保持链接的活跃。这里是新的链接：http://www.mathworks.com/help/matlab/matlab_prog/add-help-for-your-program.html和http://www.mathworks.com/help/matlab/matlab_prog/display-custom-documentation.html。 - yuk

1

这些较新的链接似乎关于文档注释的信息要少得多 :( - Ben Voigt

显示剩余2条评论

3个回答

5

我认为在帮助格式化方面最重要的方面是确保有帮助文档，并且您的格式一致，这样您（以及与您合作的人）就不会浪费时间寻找信息。请注意，对于OOP，有一个具有“帮助”方法的超类很有用，该方法调用doc(class(obj))，因为您无法轻松访问类的实例的帮助。

为了帮助我保持一致（并确保我没有忘记任何东西），我在文件交换中创建了一个自动函数模板。

以下是最小标头。

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
%

- Jonas

4

我想这方面应该是有一些资料的（见示例），但我从未找到适当的文档。我经常遇到这样的代码块：

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

而且“另请参阅”部分被格式化为标题，但是如果您将“另请参阅”替换为其他内容，则无法正常工作。如果有人找到这些支持的标题列表，请在此处链接！

编辑：

我最近了解到MATLAB内置的发布系统。它似乎支持某种形式的标记语言，与Markdown的语法（如SO本身上使用的）类似，并支持LaTeX方程式等。

“Loren on the art of MATLAB”发布了一篇简短介绍关于发布和标记。有关完整的参考，请参见Mathworks网站上的Making Up MATLAB Comments for Publishing。

当您的代码准备好后，您可以使用publish()函数将结果导出为HTML / PDF / XML等。我使用以下代码段来导出我的文件：

    % 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);

- André Caron

感谢你的发现，点赞。有趣的是，“另请参阅”部分将在帮助浏览器中的最后显示。而现有的函数将链接到其帮助页面。 - yuk

网页内容由stack overflow 提供, 点击上面的

可以查看英文原文，
原文链接

- Andrew Janke · Accepted Answer

试试官方文档中的另一个部分，它更为详细。MATLAB > 用户指南 > 桌面工具和开发环境 > 自定义帮助和演示文稿 > 提供您自己的帮助和演示文稿。其中既描述了简单的帮助文本，也涵盖了生成单独的 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()可以从您函数的帮助文本中自动生成一个Contents.m文件。
H1行中的函数名称全部大写，不管函数签名中实际的大小写。
“See also”中的大小写要注意。我不确定所有情况都适用；但这种情况肯定适用。
“See also:”后面的函数名全部大写。方法名称是限定的；我认为当前方法所在类别中的方法名称可以不加限定。

在H1行和“Examples:”之间的所有内容只是一种常规格式，我觉得它更可读；help()不会对其进行特殊处理。

您可以在帮助文本中使用有限的超链接形式。特别地，您可以使用超链接来调用任意的Matlab命令，并通过使其调用help()来指向帮助文本的其他部分。您可以使用此功能指向任何函数；“function>subfunction”只是help()调用中寻址子函数的语法。不幸的是，由于您需要在这些超链接中放置“help”或“doc”，因此它仅适用于两种演示形式之一。如果有一种直接的帮助文本超链接形式会更好。