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))
*/