MATLAB m文件有助于格式化

时间：2010-10-01 15:32:05

标签： matlab formatting

我找不到可用于为您自己的MATLAB函数编写帮助的格式。信息很少in official documentation。

您是否了解使用帮助浏览器（而非帮助功能）可以看到的任何其他格式？就像内置功能一样。如何格式化标题（如语法，描述，示例）？子弹，桌子可能吗？ 或者可能是一个单独的文件？

我尝试过用于PUBLISH和HTML的文本标记，但没有用。

我发现只有一件有趣的事情。如果您的函数包含混合大小写，例如testHelpFunction，则其名称将突出显示：

alt text

如果只是testhelpfunction，则不突出显示。

还有其他想法吗？

更新

以下是我在创建您自己的帮助文件时发现的大量文档：

Providing Your Own Help and Demos
（死链接替换为Web存档链接）

（删除死链接）

再次更新：

3 个答案:

答案 0 :(得分：14)

请在官方文档中尝试此其他部分。它更彻底。 MATLAB＆gt;用户指南＆gt;桌面工具和开发环境＆gt;自定义帮助和演示＆gt;提供您自己的帮助和演示。这描述了简单的帮助文本和生成单独的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行和“例子：”之间的所有内容都只是我认为可读的传统格式; help（）不会特别对待它。

您可以在帮助中使用有限形式的超链接。特别是，您可以使用超链接来调用任意Matlab命令，并通过调用help（）指向helptext的其他部分。您可以使用它指向任何功能; “function＆gt; subfunction”只是解决help（）调用中子函数的语法。不幸的是，由于您需要在这些超链接中放置“帮助”或“doc”，它只能在一种或另一种表示形式中使用。如果有直接的帮助文本超链接形式会更好。

答案 1 :(得分：4)

我认为有一些（参见示例），但我从未找到相应的文档。我经常有这样的块：

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

并且See also部分被格式化为标题，但如果您用其他内容替换See also，则它不起作用。如果有人找到此类支持的标题列表，请在此处链接到它！

修改：

我最近开始学习matlab的内置发布系统。似乎MATLAB注释支持某种形式的标记，而不是Markdown的语法（如SO本身所使用的那样），支持LaTeX方程式和所有。

“Loren on the MATLAB”上发表了一篇关于发布和标记short introduction的帖子。有关完整参考，请参阅Mathworks网站上的Making Up MATLAB Comments for Publishing。

当您的代码准备就绪后，您可以使用publish() function将结果导出为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);

答案 2 :(得分：4)

我认为帮助格式化中最重要的方面是有一个帮助，并且您的格式是一致的，以便您（以及与您合作的人）不会浪费时间找出如何查找信息。请注意，对于OOP，使用调用doc(class(obj))的'help'方法的超类非常有用，因为您无法从类的实例化中轻松访问帮助

为了帮助我保持一致（并确保我不忘记的东西），我在文件交换上创建了一个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
%
相关问题
最新问题