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