MATLAB m文件帮助格式化 [英] MATLAB m-file help formatting
问题描述
我无法找到可用于编写自己的MATLAB函数的格式。在官方文档中
（死链接取代网页档案连结）
（去掉死链接）
> 再次更新：
在官方文档中试试这个其他部分。这是更彻底。 MATLAB>用户手册>桌面工具和开发环境>自定义帮助和演示>提供您自己的帮助和演示。这里描述了两个简单的helptext和生成单独的HTML帮助文件。
这里是我找到的帮助文本格式。 b $ b
函数foo（x，y，z）
％FOO单行描述到这里
％
％foo（x， y，z）
％
％描述性文字的多行段落在这里。对于他们来说
％的跨度线就可以了。它被视为预先格式化的文本; help（）和doc（）不会
％重新换行。在编辑器中，您可以突出显示段落，右键单击
％并选择包裹选定的注释以重新流动文本。
％
％更详细的帮助在< a href =matlab：help foo> extended_help>扩展帮助< / a> ;.
％这是这样的，所以你可以保留主要的帮助富文本
％在一个单一的屏幕上，然后打破晦涩的部分分开的部分。
％
％示例：
％foo（1,2,3）
％
％另请参阅：
％BAR
％SOMECLASS / SOMEMETHOD
disp（x + y + z）;
函数extended_help
％EXTENDED_HELP一些额外的技术细节和示例
％
％以下是您要添加其他示例，技术讨论，
％文档在模糊的功能和选项，等等。
错误（'这是一个占位符函数for helptext'）;
- 函数签名后的第一行称为H1行 。它需要只是一行，所以它可以通过contentrpt（）正确拾取，它可以从你的函数中的帮助文本自动生成一个Contents.m文件。
- H1行中的函数名无论签名中的函数名称的实际大小写是否全部大写
- 大小写关于另请参见。我不确定所有案件的工作。这一点确实如此。
- See also：之后的函数名称都是大写字母。方法名称是合格的;我认为与当前方法相同的类中的方法名可以是不合格的。
H1行与Examples：只是一个传统的格式，我觉得可读; help（）不会特别对待它。
您可以在帮助中使用有限形式的超链接。特别是，您可以使用超链接来调用任意的Matlab命令，并通过调用help（）来指向helptext的其他部分。你可以用它来指向任何函数; function> subfunction只是在help（）调用中寻址子函数的语法。不幸的是，由于您需要在这些超链接中放置帮助或文档，因此只能以一种或另一种表示形式进行操作。如果有一个直接的helptext超链接表单会更好。
I could not find what formatting available to write help for your own MATLAB function. Very little information is available in official documentation.
Do you know about any other formatting that can be visible with Help Browser (not with help function)? As it is for built-in functions. How to format headings (like Syntax, Description, Examples)? Are bullets, tables possible? Or may be it should be a separate file?
I've tried text markup as used for PUBLISH and HTML, didn't work.
I found only one interesting thing. If your function contains mixed case, like testHelpFunction, its name will be highlighted:
No highlighting if it's just testhelpfunction.
Any other thoughts?
UPDATE
Here is extensive documentation I found on creating your own help files:
Providing Your Own Help and Demos
(Dead link replaced with web archive link)
(Dead link removed)
Updated again:
Try this other section in the official documentation. It's more thorough. MATLAB > User's Guide > Desktop Tools and Development Environment > Customizing Help and Demos > Providing Your Own Help and Demos. This describes both simple helptext and generating separate HTML help files.
Here's the helptext formatting I've picked up on and found useful.
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');
- The first line after the function signature is called the "H1 line". It needs to be just one line so it is properly picked up by contentsrpt(), which can autogenerate a Contents.m file from the helptext in your functions
- The function name in the H1 line is all caps, regardless of actual capitalization of the function name in the signature
- Case matters for the "See also". I'm not sure which all cases work; this one does for sure.
- Function names after "See also:" are all caps. Method names are qualified; I think names of methods in the same class as the current method can be unqualified.
Everything between the H1 line and "Examples:" is just a conventional formatting that I find readable; help() doesn't treat it specially.
You can use a limited form of hyperlinks in help. In particular, you can use hyperlinks to invoke arbitrary Matlab commands, and point to other sections of helptext by having it invoke help(). You can use this to point to any function; "function>subfunction" is just the syntax for addressing subfunctions in help() calls. Unfortunately, since you need to put either "help" or "doc" in those hyperlinks, it only works in one or the other presentation form. It would be nicer if there were a direct helptext hyperlink form.
这篇关于MATLAB m文件帮助格式化的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！
