MATLAB m文件有助于格式化

Question

我找不到可用于为您自己的MATLAB函数编写帮助的格式.官方文档中提供的信息非常少.

您是否知道使用帮助浏览器可以看到的任何其他格式(不具有帮助功能)？就像内置功能一样.如何格式化标题(如语法,描述,示例)？子弹,桌子可能吗？或者它应该是一个单独的文件？

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

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

没有突出显示它是否正好testhelpfunction.

还有其他想法吗？

UPDATE

以下是我在创建您自己的帮助文件时找到的大量文档:

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

---

(已删除死链接)

---

再次更新:

• 添加程序帮助
• 显示自定义文档

Answer 1

请在官方文档中尝试此其他部分.它更彻底.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()正确选取,它可以从函数的helptext中自动生成Contents.m文件.
• 无论签名中函数名称的实际大小写如何,H1行中的函数名称都是大写字母
• 案件对"另见"也很重要.我不确定所有案例都有效; 这个肯定是有道理的.
• "参见:"之后的函数名称都是大写字母.方法名称合格; 我认为与当前方法在同一类中的方法名称可能是不合格的.

H1系列和"例子:"之间的所有内容都只是我认为可读的传统格式; help()不会特别对待它.

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

Answer 2

我认为帮助格式最重要的方面是有帮助，并且格式是一致的，这样您（和与您一起工作的人）就不会浪费时间寻找如何查找信息。请注意，对于 OOP，具有调用 'help' 方法的超类很有用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
%