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