doctest

doctest copied to clipboard

The documentation has a section called Hiding examples from Haddock for things that you want to be doctests but not show up in the Haddock. I'd like to do the opposite; have examples that show up in Haddock but are not recognized by doctest. For example, for example code that isn't fully specified, or for examples that do IO which would be unsuitable to do in a test runner.

>>> launchTheMissiles
Launching...
Target destroyed

👍 for this. I'm also interested in this feature. For example, you have something like getCurrentTime inside your >>> code block. But you still want to have GHCI-like example in your documentation.

Why not just use a different prompt for examples you don't want doctest to run?

This example runs

  >>> 1 + 1
  2

This example doesn't

  λλλ launchTheMissles
  Launching...
  Target destroyed

Is the meaning of that clear to you as a reader?

I think it's better to use ghci> custom prompt instead of λλλ. Looks clear enough to me.

@chris-martin Hey, thanks for taking the time to open this issue and sorry for the late reply!

How would you want to specify that a specific example should be ignored by doctest?

@sol Good question. I don't think there's any immediately obvious answer.

If you nest a comment, it doesn't show up in the haddock, so how about adding something like this:

If an example is preceded by {- no doctest -}, then doctest will not run it.

That would be fine with me. However, it may be that the nested comment is already stripped by GHC (it may even be a bug, not sure). In that case doctest would not have access to it neither.

Can somebody find out?

I don't have time to work on this myself but I would accept a PR if it is high quality (which includes tests that were written using test driven development; unless the properties in question are enforced by parametrism) (bad old code does not justify writing bad new code).

One more question, does it work in >-style comments too?