Спецификация функций (Документирование функций)

Для  каждой  пользовательской  функции  должна  быть  описана  в  виде  комментария спецификация, содержащая следующую информацию:

§ назначение функции;

§ описание семантики параметров-значений (параметров, передаваемых по значению); описание  семантики параметров-переменных  (параметров,  передаваемых  по ссылке);

§ описание семантики возвращаемого значения;

§ Если функция реализует какой-либо вычислительный метод (например: нахождение площади фигуры методом трапеций, поиск минимума функции методом Ньютона и т.п.), рекомендуется в теле функции поместить комментарий с кратким описанием метода, либо ссылку на источник, где описан метод.

 

Для предоставления справки (спецификации) о программе или функции используются комментарии, расположенные между первой командой и определением функции. Эти строки будут отображены при выполнении команды help с именем программы или функции.

function [alpha, beta] = swap (alpha, beta)

% Функция меняет значения аргументов

% alpha -- 1е число

% beta -- 2е число

x = alpha;

alpha = beta;

beta = x;

end

Для этой функции выполнение команды

>> help swap

даст следующий результат.

Функция меняет значения аргументов

alpha -- 1е число

beta -- 2е число

Строка, следующая за строкой определения функции, называется H1 строкой помощи. Именно она будет отображаться первой при выполнении команды help и предоставлять обобщающую информацию о функции. Очень важно сделать эту строку как можно более описательной, т.к. она используется для поиска функции по ключевым словам функцией lookfor, и окном Function Browser (вызывается по «Shift+F1») для поиска функций.