# doc-cache created by Octave 11.2.0
# name: cache
# type: cell
# rows: 3
# columns: 1
# name: <cell-element>
# type: sq_string
# elements: 1
# length: 7
doctest


# name: <cell-element>
# type: sq_string
# elements: 1
# length: 5877
 -- doctest TARGET
 -- doctest TARGET -nonrecursive
 -- SUCCESS = doctest (TARGET, ...)
 -- [NUMPASS, NUMTESTS, SUMMARY] = doctest (...)
     Run examples embedded in documentation.

     Doctest finds and runs code found in TARGET, which can be a:
        • function;
        • class;
        • Texinfo file;
        • .oct/.mex compiled code;
        • directory/folder (pass ‘-nonrecursive’ to skip subfolders);
        • cell array of such items.
     When called with a single return value, return whether all tests have
     succeeded (SUCCESS).

     When called with two or more return values, return the number of tests
     passed (NUMPASS), the total number of tests (NUMTESTS) and a structure
     SUMMARY with various fields.

     Doctest finds example blocks, executes the code and verifies that the
     results match the expected output.  For example, running ‘doctest doctest’
     will execute this code:

          >> 1 + 3
          ans =
               4

     If there's no output, just put the next line right after the one with no
     output.  If the line does produce output (for instance, an error), this
     will be recorded as a test failure.

          >> x = 3 + 4;
          >> x
          x =
             7

     *Wildcards* You can use a wildcard to match unpredictable output:

          >> disp(datestr(now, 'yyyy-mm-dd'))
          2...

     *Expecting an error* Doctest can deal with errors, to some extent.  For
     instance, this case is handled correctly:

          >> not_a_real_function(42)
          error: ...ndefined ...

     Note use of wildcards here; MATLAB spells this ‘Undefined’, while Octave
     uses ‘undefined’.  Writing ‘error: ’ is optional.  Currently errors do not
     work if the code emits other output before the error message.  Warnings are
     different; they work fine.

     *Multiple lines of code* Code spanning multiple lines can be entered by
     prefixing all subsequent lines with ‘..’, e.g.,

          >> for i = 1:3
          ..   i
          .. end
          i = 1
          i = 2
          i = 3
     (But note this is not required when writing texinfo documentation, see
     below).

     *Shortcuts* You can optionally omit ‘ans = ’ when the output is unassigned.
     But actual variable names (such as ‘x = ’) must be included.  Leading and
     trailing whitespace on each line of output will be discarded which gives
     some freedom to, e.g., indent the code output as you wish.

     *Directives* You can skip certain tests by marking them with a special
     comment.  This can be used, for example, for a test not expected to pass or
     to avoid opening a figure window during automated testing.

          >> a = 6         % doctest: +SKIP
          b = 42
          >> plot(...)     % doctest: +SKIP

     These special comments act as directives for modifying test behaviour.  You
     can also mark tests that you expect to fail:

          >> a = 6         % doctest: +XFAIL
          b = 42

     Both the ‘+SKIP’ and the ‘+XFAIL’ directives have conditional variants
     (e.g., ‘+SKIP_IF’ and ‘+SKIP_UNLESS’) that control test execution and
     expectations based on runtime conditions, such as the platform, operating
     systems, or installed packages:

          >> license       % doctest: +XFAIL_IF(DOCTEST_MATLAB)
          ans = GNU General Public License...

     Doctest provides the default flags ‘DOCTEST_OCTAVE’ and ‘DOCTEST_MATLAB’,
     but you can call functions and access arbitrary variables (including those
     defined by previous tests).

     By default, all adjacent white space is collapsed into a single space
     before comparison.  A stricter mode where "internal whitespace" must match
     is available:

          >> fprintf('a   b\nc   d\n')
          a b
          c d

          >> fprintf('a   b\nc   d\n')    % doctest: -NORMALIZE_WHITESPACE
          a   b
          c   d

     To disable the ‘...’ wildcard, use the ‘-ELLIPSIS’ directive.

     *Numerical Format* Tests are run using default formatting:
          >> 6/5
          ans = 1.2000

     If your test changes the global state (e.g., ‘format’ or ‘chdir’), you may
     need to undo your changes afterwards.  In this example, we followup with
     ‘format’ to reset to the default five digits:

          >> format long
          >> 355/113
          ans = 3.14159292035...
          >> format

     *Diary Style* When the m-file contains plaintext documentation, doctest
     finds tests by searching for lines that begin with ‘>>’.  It then finds the
     expected output by searching for the next ‘>>’ or two blank lines.

     *Octave/Texinfo Style* If your m-file contains Texinfo markup, then doctest
     finds code in ‘@example ... @end example’ blocks.  Note:
        • The two-blank-lines convention is not required.
        • The use of ‘>>’ is neither required nor recommended as Octave
          documentation conventionally indicates output with ‘@result{}’ and
          ‘@print{}’.  Ambiguities are resolving by assuming output is indented
          further than input.

     A typical Texinfo-style doctest looks like:
          a = 5;
          b = a + 1
            ⇒ b = 6
          disp("hello\nthere")
            ⊣ hello
            ⊣ there

     The two styles are not mutually exclusive: this documentation is written in
     Texinfo using a hybrid approach.

     *Support for non-ASCII characters* If you encounter file encoding issues on
     Octave, see dir_encoding and __mfile_encoding__.  For example, this file
     itself is encoded in utf-8 and declares this by installing a ‘.oct-config’
     file.  Matlab users might want to try ‘feature('DefaultCharacterSet',
     'UTF-8')’.

     See also: test.


# name: <cell-element>
# type: sq_string
# elements: 1
# length: 39
Run examples embedded in documentation.





