Форматирование справки m файла MATLAB

Ответ 1

Попробуйте другой раздел в официальной документации. Это более основательно. MATLAB > Руководство пользователя > Инструменты для рабочего стола и среда разработки > Настройка справки и демонстраций > Предоставление вашей собственной справки и демонстраций. Это описывает как простой helptext, так и генерирует отдельные файлы справки HTML.

Здесь форматирование helptext, которое я нашел и нашел полезным.

function foo(x,y,z)
%FOO One-line description goes here
%
% foo(x,y,z)
%
% Multi-line paragraphs of descriptive text go here. It fine for them to
% span lines. It 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 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". Это должна быть только одна строка, поэтому она правильно подобрана contentrpt(), которая может автогенерировать файл Contents.m из helptext в ваших функциях.
• Имя функции в строке H1 - это все кепки, независимо от фактической капитализации имени функции в сигнатуре
• Дело имеет значение для "См. также". Я не уверен, что все дела работают; это точно.
• Названия функций после "Смотрите также:" - это все шапки. Имена методов квалифицированы; Я думаю, что имена методов в том же классе, что и текущий метод, могут быть неквалифицированы.

Все между линией H1 и "Примеры:" - это просто обычное форматирование, которое я считаю читаемым; help() не относится к нему специально.

Вы можете использовать ограниченную форму гиперссылок в справке. В частности, вы можете использовать гиперссылки для вызова произвольных команд Matlab и указывать на другие разделы helptext, ссылаясь на help(). Вы можете использовать это, чтобы указать на любую функцию; "function > subfunction" - это просто синтаксис для адресации подфункций в вызовах help(). К сожалению, поскольку в этих гиперссылках вам нужно поместить либо "помощь", либо "doc", она работает только в одной или другой форме презентации. Было бы лучше, если бы была прямая гиперссылка гипертекста.

Ответ 2

Я полагаю, что есть некоторые (см. пример), но я никогда не нашел соответствующую документацию. У меня часто есть такие блоки:

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

И часть See also отформатирована как заголовок, но если вы замените See also на что-то еще, это не сработает. Если кто-либо найдет список таких поддерживаемых титров, пожалуйста, обратитесь к нему здесь.

ИЗМЕНИТЬ

Недавно я узнал о встроенной издательской системе Matlab. Кажется, что комментарии MATLAB поддерживают некоторую форму разметки, не так далеко от синтаксиса Markdown (как используется на самой SO), с поддержкой уравнений LaTeX и всего.

Там размещена статья "Лорен по искусству MATLAB" с кратким введением по публикации и разметке. Полную ссылку см. В Создание комментариев MATLAB для публикации на веб-сайте Mathworks.

Когда ваш код готов, вы можете экспортировать результат в HTML/PDF/XML и т.д., используя функцию publish(). Для экспорта файлов я использую следующий фрагмент:

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

Ответ 3

Я думаю, что самый важный аспект в форматировании справки заключается в том, что есть помощь вообще и что ваше форматирование согласовано, так что вы (и люди, работающие с вами) не теряете времени, узнавая, как искать Информация. Обратите внимание, что для ООП полезно иметь суперкласс с "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
%