Re: Python-style doctests in Guile (implemented, please comment)

["Vítor De Araújo" <vbuaraujo@sapo.pt>]

Another possibility beside docstrings would be to add it as a property
to the function. I'm not sure if this is a documented feature, but if
the first form in a function is a literal vector rather than a string
(or in addition to a string, I've just found out!), it will be
interpreted as a sequence of (KEY . VAL) properties to the function. For
example:

(define (double x)
  "Returns twice the value of a given number."
  #((examples [(double 5) 10]
              [(double 0) 0]))
  (* 2 x))

scheme@(guile-user)> (procedure-properties double)
$2 = ((name . double) (documentation . "Returns twice the value of a
given number.") (examples ((double 5) 10) ((double 0) 0)))

scheme@(guile-user)> (procedure-property double 'examples)
$3 = (((double 5) 10) ((double 0) 0))


On 31/07/2017 14:23, Arne Babenhauserheide wrote:
> Hi Mark,
> 
> String-literals are a problem I did hit, and I’d be happy to lose that
> problem without losing the ease of starting a procedure with tests which
> double as automatically verified documentation.
> 
> Mark H Weaver <mhw@netris.org> writes:
>>>     (import (examples doctests))
>>>     
>>>     (define (one)
>>>       "(test 'foo
>>>          (test-equal 1 (one)))"
>>>       1)
>>
>> While it may sometimes be beneficial to include a few
>> examples in the documentation, a full test suite does not, IMO, belong
>> in the doc string.
> 
> I think there’s a misconception here: These doctests are not intended to
> replace a full test suite. They provide simple tests which double as
> automatically verified documentation.
> 
> This is why I asked whether what I implemented is too complex (by
> providing all of srfi-64 here). If you get clear benefits from
> editor-support, the test is typically too complex for a doctest.
> However editor-support could be provided as it is for org-mode: By
> editing the region in a specialized sub-buffer.
> 
> The tests here are first-of-all intended for humans to read.
> 
> Why does code in string-literals bring a loss of hygiene? I’s read in
> the module as if it had been written directly in a lambda and read
> during parsing. Am I missing something or are you envisioning mutation
> of the string prior to reading and evaluating it?
> 
> Panicz Maciej Godek <godek.maciek@gmail.com> writes:
>> I agree with Mark, that putting tests inside a string in Lisp is a
>> terrible idea, because Lisp doesn't have Python's shortcommings,
> …
>> There is no point in trading something better for something worse merely
>> because people from Python (or elsewhere) can't afford this "better".
> 
> This doesn’t correctly represent the situation of Python. It is
> perfectly possible in Python to write tests in literal code — for
> example by using attributes of a function to hold functions which run
> the tests.
> 
> What doctests provide is a way to write example usage first and foremost
> for humans, directly at the top of the function definition, and have it
> checked automatically to ensure that these examples in auto-generated
> documentation actually work and keep working.
> 
> Using a define-with-tests (or define-with-examples) does not allow
> writing for humans first, so it does not reach feature-parity. I could
> use pretty-print to create an examples section of the documentation, but
> I won’t know how it is going to be formatted while writing the code.
> (though this need not be a pure drawback)
> 
> This is why I’m looking into doctests in the first place. If you have
> something which provides feature parity, I’m all for using that
> instead. Requirements:
> 
> - Can be verified automatically.
> - Becomes part of auto-generated documentation.
> - Is "physically" close to the definition of the procedure (same file,
>   no other definitions between the tests/examples and the procedure).
> 
> Ideally it should look like what I’d run in the REPL to use the
> procedure, but I don’t think that this must be a hard requirement.
> 
> Best wishes,
> Arne
> 

-- 
Vítor De Araújo
https://elmord.org/