我找不到可用于为您自己的MATLAB函数编写帮助的格式。in official documentation提供的信息非常少。
您是否知道可以通过帮助浏览器(而不是帮助功能)查看的其他格式?就像内置函数一样。如何格式化标题(如语法、描述、示例)?项目符号和表格可以吗?或者应该是一个单独的文件?
我尝试过将文本标记用于发布和HTML,但不起作用。
我只发现了一件有趣的事。如果您的函数包含混合大小写,如testHelpFunction
,则其名称将突出显示:
如果只是testhelpfunction
,就不会高亮显示。
还有其他想法吗?
更新
下面是我找到的有关创建您自己的帮助文件的大量文档:
Providing Your Own Help and Demos
(死链接替换为web存档链接)
(已删除死链接)
再次更新:
发布于 2010-10-02 01:17:32
请尝试官方文档中的其他部分。它更彻底。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行和"Examples:“之间的所有内容都是我认为可读的常规格式;help()并没有特别处理它。
您可以在“帮助”中使用有限形式的超链接。特别是,您可以使用超链接来调用任意的Matlab命令,并通过让帮助文本调用help()来指向帮助文本的其他部分。您可以使用它来指向任何函数;"function>subfunction“只是在help()调用中寻址子函数的语法。不幸的是,由于您需要在这些超链接中添加"help“或"doc”,因此它只能以一种或另一种形式出现。如果有一个直接的帮助文本超链接形式就更好了。
发布于 2010-10-02 04:36:19
我认为帮助格式化最重要的方面是有帮助,并且您的格式是一致的,这样您(和与您一起工作的人)就不会浪费时间去寻找如何查找信息。请注意,对于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
%
发布于 2010-10-01 23:35:42
我认为有一些(参见示例),但我从来没有找到适当的文档。我经常遇到这样的问题:
% ...
%
% See also:
% this_other_function()
%
% <author>
并且See also
部件被格式化为标题,但是如果您将See also
替换为其他内容,它将不起作用。如果有人找到这类支持的书目列表,请链接到此处!
编辑
我最近了解了matlab的内置发布系统。似乎MATLAB注释支持某种形式的标记,与Markdown的语法(就像在so本身上使用的一样),并支持LaTeX等式。
有一篇名为"Loren on the art of 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);
https://stackoverflow.com/questions/3840657
复制相似问题