Re: @example's as doctests

[Oliver Heimlich]

Am 02.02.2015 um 18:42 schrieb Colin Macdonald:
> I've recently learned how to use address@hidden to put the expected result
> into the texinfo docs of my functions.  (Thanks to "interval" pkg dev!)
>
> Is there any existing way to run these as tests?  Like doctest in
> Python?  I.e., extract them, run them, make sure the output matches the
> address@hidden  The documentation refers to "example" but that seems to
> pull in `%!demo` blocks instead.

The @result{} is just a macro that produces the ⇒ symbol in the 
documentation. I find it useful for short examples in the documentation. 
I copy the console output into the @example, replacing “$variable = ” 
with the macro.

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.

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,
 - if you wanted to check the console output of the examples, you would 
have to intercept the stdout,
 - some results may be system-dependent,
 - …

> I expect the answer will be "no, but please write such a thing"... :(

I'd find it useful to code simple %!test blocks, which will be used to 
generate additional @example blocks at the end of the documentation. 
Perhaps introduce a new %!example block?! However, automating this is 
probably not worth it, since this only makes sense for short code 
snippets and the examples in the documentation usually do not change often.