Info Catalog octave: Exception and Error Handling in Oct-Files octave: Oct-Files

octave: Documentation and Testing of Oct-Files

 
 A.1.13 Documentation and Testing of Oct-Files
 ---------------------------------------------
 
 The documentation for an oct-file is contained in the fourth string
 parameter of the ‘DEFUN_DLD’ macro.  This string can be formatted in the
 same manner as the help strings for user functions, however there are
 some issues that are particular to the formatting of help strings within
 oct-files.
 
    The major issue is that the help string will typically be longer than
 a single line of text, and so the formatting of long multi-line help
 strings needs to be taken into account.  There are several possible
 solutions, but the most common is illustrated in the following example,
 
      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")
      {
      ...
      }
 
 where each line of text is terminated by ‘\n\’ which is an embedded
 newline in the string together with a C++ string continuation character.
 Note that the final ‘\’ must be the last character on the line.
 
    Octave also includes the ability to embed test and demonstration code
 for a function within the code itself (Test and Demo Functions).
 This can be used from within oct-files (or in fact any file) with
 certain provisos.  First, the test and demo functions of Octave look for
 ‘%!’ as the first two characters of a line to identify test and
 demonstration code.  This is a requirement for oct-files as well.  In
 addition, the test and demonstration code must be wrapped in a comment
 block to avoid it being interpreted by the compiler.  Finally, the
 Octave test and demonstration code must have access to the original
 source code of the oct-file—not just the compiled code—as the tests are
 stripped from the compiled code.  An example in an oct-file might be
 
      /*
      %!assert (sin ([1,2]), [sin(1),sin(2)])
      %!error (sin ())
      %!error (sin (1,1))
      */
 

Info Catalog octave: Exception and Error Handling in Oct-Files octave: Oct-Files