A.1.13 Документирование и тестирование файлов Oct ¶

Документация для файла oct содержится в четвёртом строковом параметре макроса DEFUN_DLD. Эта строка может быть отформатирована так же, как и строки справки для пользовательских функций, однако есть некоторые особенности, специфичные для форматирования строк справки в файлах oct.

Основная проблема заключается в том, что строка справки обычно длиннее одной строки текста, поэтому необходимо учитывать форматирование длинных многострочных строк справки. Существует несколько возможных решений, но наиболее распространённым является следующий пример:

DEFUN_DLD (do_what_i_want, args, nargout,
  "-*- texinfo -*-\n\
@deftypefn {} {} do_what_i_say (@var{n})\n\
A function that does what the user actually wants rather\n\
than what they requested.\n\
@end deftypefn")
{
...
}

где каждая строка текста завершается \n\, что является встроенным символом новой строки вместе с символом продолжения строки C++. Обратите внимание, что заключительный символ \ должен быть последним символом в строке.

Octave также позволяет встраивать тестовый и демонстрационный код для функции непосредственно в код (см. Тестовые и демонстрационные функции). Это можно использовать внутри файлов oct (или, в принципе, в любом файле) при соблюдении определённых условий. Во-первых, тестовые и демонстрационные функции Octave ищут %! в качестве первых двух символов строки, чтобы определить тестовый и демонстрационный код. Это требование и для файлов oct. Кроме того, тестовый и демонстрационный код должен быть заключён в блок комментариев, чтобы избежать его интерпретации компилятором. Наконец, тестовый и демонстрационный код Octave должен иметь доступ к исходному коду файла oct, а не только к скомпилированному коду, так как тесты удаляются из скомпилированного кода. Пример в файле oct может быть таким:

/*
%!assert (sin ([1,2]), [sin(1),sin(2)])
%!error (sin ())
%!error (sin (1,1))
*/