Re: @example's as doctests

[Colin Macdonald]

On 28/03/15 14:14, Jordi Gutiérrez Hermoso wrote:
> How about we just give you push access and you start pushing them
> yourself?
>
> I mean, I still am willing to help you rewrite the docs, but I don't
> see any reason why you shouldn't be allowed to modify our codebase
> directly.

Maybe in principle, don't promise I'll do very much!

But to get started here's a patch for svd.  Some comments/questions:

1.  @example is not (semantically) a good alternative to tex.
    I used @verbatim as in this patch (and I think Oliver does
    the same in Interval).  But then how far to indent?


2.  This code (and others I've seen) split the command and
    the output across multiple @examples.  I propose changing
    this:
    @example
      some cmd
    @end example
    returns
    @example
    some output
    @end example

    into this:
    @example
      some cmd
      @result {} some output
    @end example

    Is that ok?


3.  "help strjoin" shows

    strjoin ({'Octave','Scilab','Lush','Yorick'}, '*')
          => 'Octave*Scilab*Lush*Yorick'

    Currently I would need to have "ans", like this

    strjoin ({'Octave','Scilab','Lush','Yorick'}, '*')
          => ans = 'Octave*Scilab*Lush*Yorick'

    But I think it might be nice to have doctest accept either,
    at least in the specific case of "ans".

svd_docs.diff
Description: Text Data