Re: @example's as doctests

[Colin Macdonald]

On 02/02/15 18:23, Oliver Heimlich wrote:
> As a package maintainer I prefer to have these examples as test cases,
> just to make sure that the documentation is correct. That's why I like
> your proposal. The simplest solution IMHO is to add a %!test block for
> examples used in the documentation manually.

Right.  But then I have to keep them in sync :(  Worse, I'll have to
check that contributors' patches do that too.

> It is complicated to check the @examples automatically, you must consider:
>  - The @example blocks must not follow any particular syntax, nor must
> they contain useful code,
>  - the author of the example blocks may have abreviated commands or
> console output,

Within any one (smallish or new) project, those are not too big a problem.      

>  - if you wanted to check the console output of the examples, you would
> have to intercept the stdout,
>  - some results may be system-dependent,

Good points.  Some of them are are solvable within any particular
toolbox.  Things like system-dependent or otherwise varying inputs are
usually flaggable as such (i.e., in Python doctest).

I've taken a look at doctest-for-matlab which I'll post about in a new
thread.

best,
Colin

signature.asc
Description: OpenPGP digital signature