doctest-for-matlab: looks good

[Colin Macdonald]

I've taken a look at:

https://github.com/catch22/doctest-for-matlab/

to run tests on my m-file documentation.  Basically, I do "doctest sym"
to test a whole class or "doctest @sym/plus" for a method.

I think I will start using this for my documentation.  I did a
half-dozen m-files and found an copy-paste error already.

Here's an example (as a diff) of the minimal changes I needed for one of
the Symbolic pkg's m-files:

- - - - - - - - - - - - - - - - - - - - - - - - -

 %% Example:
 %% @example
 %% @group
-%% syms x
-%% p = poly2sym ([2 4 6 8], x)
-%%    @result{}
+%% >> syms x
+%% >> p = poly2sym ([2 4 6 8], x)
+%% p = (sym)
 %%          3      2
 %%       2⋅x  + 4⋅x  + 6⋅x + 8
-%% horner (p)
-%%    @result{} x⋅(x⋅(2⋅x + 4) + 6) + 8
+%% >> horner (p)
+%% ans = (sym) x⋅(x⋅(2⋅x + 4) + 6) + 8
+%%
+%%
 %% @end group
 %% @end example

- - - - - - - - - - - - - - - - - - - - - - - - -

Notes:

1.  Use ">>" to indicate commands to be run.  And it needs two blank
lines before regular paragraphs start again (I've just been using two
blank lines within the @example).  There are various wildcard options
and its fairly flexible wrt whitespace.

2.  It runs on the output of `__makeinfo__(docstring, "plain text")` so
it has/requires no texinfo knowledge.

3.  Only downside I see so far is the two blank lines can be a bit too
"open" in the "help @sym/horner" output.

It had some preliminary Octave support already and I hacked on it a
little more: upstream was happy to merge.  We have no "evalc" yet
(captures the stdout, https://savannah.gnu.org/patch/?8033).  I wrote a
quick-n-dirty hack using diary which is now in doctest-for-matlab.
There are still some upstream bugs to work out about counting/displaying
failures on classes.

best,
Colin

-- 
Colin Macdonald
Associate Professor
Tutorial Fellow at Oriel College
University of Oxford

signature.asc
Description: OpenPGP digital signature