MATLAB Language
Функции документирования

замечания

Простая функциональная документация

function output = mymult(a, b)
% MYMULT Multiply two numbers.
%   output = MYMULT(a, b) multiplies a and b.
%
%   See also fft, foo, sin.
%
%   For more information, see <a href="matlab:web('https://google.com')">Google</a>.
    output = a * b;
end

help mymult затем предоставляет:

mymult Умножьте два числа.

output = mymult (a, b) умножает a и b.

См. Также fft, foo, sin.

Для получения дополнительной информации см. Google .

fft и sin автоматически ссылаются на соответствующий текст справки, а Google - это ссылка на google.com . foo не будет ссылаться на какую-либо документацию, если нет документальной функции / класса по имени foo на пути поиска.

Локальная функциональная документация

В этом примере документацию для локальной функции baz (определенную в foo.m ) можно получить либо по полученной ссылке в help foo , либо через help foo>baz .

function bar = foo
%This is documentation for FOO.
% See also foo>baz

% This wont be printed, because there is a line without % on it.
end

function baz
% This is documentation for BAZ.
end

Получение сигнатуры функции

Часто бывает полезно, чтобы MATLAB печатал 1- ^ю строку функции, так как обычно она содержит подпись функции, включая входы и выходы:

dbtype <functionName> 1

Пример:

>> dbtype fit 1

1  function [fitobj,goodness,output,warnstr,errstr,convmsg] = fit(xdatain,ydatain,fittypeobj,varargin)

Документирование функции с помощью сценария примера

Чтобы документировать функцию, часто полезно иметь пример скрипта, который использует вашу функцию. Функция публикации в Matlab затем может быть использована для создания файла справки со встроенными изображениями, кодом, ссылками и т. Д. Синтаксис для документирования вашего кода можно найти здесь .

Функция Эта функция использует «исправленный» FFT в Matlab.

function out_sig = myfft(in_sig)

out_sig = fftshift(fft(ifftshift(in_sig)));

end

Пример сценария Это отдельный сценарий, который объясняет входы, выходы и дает пример, объясняющий, почему необходима коррекция. Благодаря У, Кан, оригинальному автору этой функции.

%% myfft
% This function uses the "proper" fft in matlab. Note that the fft needs to
% be multiplied by dt to have physical significance.
% For a full description of why the FFT should be taken like this, refer
% to: Why_use_fftshift(fft(fftshift(x)))__in_Matlab.pdf included in the
% help folder of this code. Additional information can be found:
% <https://www.mathworks.com/matlabcentral/fileexchange/25473-why-use-fftshift-fft-fftshift-x----in-matlab-instead-of-fft-x-->
%
%% Inputs
% *in_sig* - 1D signal
% 
%% Outputs
% *out_sig* - corrected FFT of *in_sig*
% 
%% Examples
% Generate a signal with an analytical solution. The analytical solution is
% then compared to the fft then to myfft. This example is a modified
% version given by Wu, Kan given in the link aboce.
%%
% Set parameters
fs = 500;           %sampling frequency
dt = 1/fs;          %time step
T=1;                %total time window
t = -T/2:dt:T/2-dt; %time grids
df = 1/T;           %freq step
Fmax = 1/2/dt;      %freq window
f=-Fmax:df:Fmax-df; %freq grids, not used in our examples, could be used by plot(f, X)
%%
% Generate Gaussian curve
Bx = 10; A = sqrt(log(2))/(2*pi*Bx);    %Characteristics of Gaussian curve
x = exp(-t.^2/2/A^2);                   %Create Gaussian Curve
%% 
% Generate Analytical solution
Xan = A*sqrt(2*pi)*exp(-2*pi^2*f.^2*A^2); %X(f), real part of the analytical Fourier transform of x(t)

%%
% Take FFT and corrected FFT then compare
Xfft = dt *fftshift(fft(x));    %FFT
Xfinal = dt * myfft(x);         %Corrected FFT
hold on
plot(f,Xan);
plot(f,real(Xfft));
plot(f,real(Xfinal),'ro');
title('Comparison of Corrected and Uncorrected FFT');
legend('Analytical Solution','Uncorrected FFT','Corrected FFT');
xlabel('Frequency'); ylabel('Amplitude');
DT = max(f) - min(f);
xlim([-DT/4,DT/4]);

Выходной параметр «Публикация» можно найти на вкладке «Опубликовать», выделенной на рисунке « Простая функциональная документация» ниже.

Matlab запустит сценарий и сохранит отображаемые изображения, а также текст, сгенерированный командной строкой. Вывод может быть сохранен во многих форматах, включая HTML, Latex и PDF.

Результат приведенного выше примера скрипта можно увидеть на изображении ниже.