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

[Arne Babenhauserheide]

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 <address@hidden> 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 <address@hidden> 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
-- 
Unpolitisch sein
heißt politisch sein
ohne es zu merken

signature.asc
Description: PGP signature