octave-maintainers
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: @example's as doctests


From: Oliver Heimlich
Subject: Re: @example's as doctests
Date: Sat, 28 Mar 2015 13:09:10 +0100
User-agent: Mozilla/5.0 (X11; Linux x86_64; rv:31.0) Gecko/20100101 Icedove/31.5.0

I noticed:
   * there are a few actual errors.

I found only one error with ldivide. The documentation string calls
mldivide by accident (bug 1) and your test happens to reveal a problem
in mldivide (bug 2). Lucky strike!

   * there are some cases of @example used as a LaTeX alternative
     (is there an @verbatim instead?)

Yes, the @example blocks have been used for ASCII art and do not contain
actual examples. The @verbatim should be a valid replacement (without
indentation). I am going to change the documentation.

   * there a few minor (cosmetic?) errors: [-1, 5] to [-1, +5]

I would consider these actual errors and am going to fix the
documentation. A very early version of the package had a different
format for the output of signs.

   * there are a couple cases were my current splitting
     input/output based on @result{} fails.  (Personally I prefer
     marking input with ">>" but the doctest code could instead be
     refactored further.)

I found several problems with doctest:

intervaltotext: The @example block contains 3 consecutive inputs and
outputs. Without the missing “>>” for inputs there is a problem with
seperating them. Would it be sufficient to use three @group blocks in
the @example block?

eq, nextout: The output is boolean, but the documentation string shows
the console output as ans = 0 (or 1). I can change the documentation to
@result{} False (or True).

mulrev: The function returns two return values and the syntax used in
the @example is probably wrong for that purpose.

Colin,

I have added a doctest target into my maintainer Makefile [1], which works out of the box together with you modifications for doctest-for-matlab.

I was able to make all doctests pass with a simple changeset [2]. There is only one thing which I am not happy with: I could only make the following example pass by splitting it into three separate @example blocks. Three @example blocks produce very poor formatting in the HTML documentation because of big margins between them. So, there should be a different solution.

## x = infsup (1 + eps);
## intervaltotext (x)
##   @result{} [1.0000000000000002, 1.0000000000000003]
## y = nextout (x);
## intervaltotext (y)
##   @result{} [1, 1.0000000000000005]
## z = infsup (1);
## intervaltotext (z)
##   @result{} [1]

Oliver

[1] https://sourceforge.net/p/octave/interval/ci/default/tree/Makefile
[2] https://sourceforge.net/p/octave/interval/ci/a1bf37f4dde28a03aa1a3cbdb50d42e476e3c75b/



reply via email to

[Prev in Thread] Current Thread [Next in Thread]