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