# doc-cache created by Octave 4.4.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: 5105
 -- 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;
        • 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:

          >> 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)
          ??? ...ndefined ...
     (Note use of wildcards here; MATLAB spells this ’Undefined’, while
     Octave uses ’undefined’).

     However, currently this does 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:

          >> "shiny Octave feature"    % doctest: +XFAIL_IF(DOCTEST_MATLAB)
          ans = shiny Octave feature

     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')    % doctest: -NORMALIZE_WHITESPACE
          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.

     *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.

     See also: test.


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





