Support for doctest style usage blocks

[ghc-mirror]

Original reporter: ezyang@

A perennial difficulty with code samples that are inline with documentation is that the samples tend to bit rot as the API changes over time: this is especially poor form for Haskell which prides itself on letting you know immediately when your code doesn't typecheck. Current modules on Hackage tend to avoid giving code examples; for APIs with complex types, this can make it excessively difficult for users to figure out how to use a library without consulting external documentation.

Python's doctest system may be a good thing to emulate: it is a combination of verified code documentation and unit testing (though I find the former use better). You can see examples of this system at Python's doctest documentation. Since Haskell does not normally support "eval", hint would probably come in handy.

If we follow Python's convention of only evaluating blocks that look like interactive sessions, there is a cosmetic question of what module name should be left of the >; Main> or ModuleName> might be good default choices.

See also discussion at http://www.mail-archive.com/haskell-cafe@haskell.org/msg39060.html

[ghc-mirror]

Original reporter: david.waern@

Good news:

Simon Hegel is working on this and has added markup for examples, looking like this:

-- | Documentation for 'f'
-- 
-- ghci> f 3
-- 15
--
f :: Int -> Int
f x = x * 5

He's got a DocTest program that is the Haskell-equivalent of python's doctest.

We're currently working on extending the Haddock API so that DocTest can get what it wants from the .haddock files.

[ghc-mirror]

Original reporter: johan.tibell@

We should probably not use ghci> as it suggests that the feature is GHC specific.

[ghc-mirror]

Original reporter: david.waern@

Yes, I've commented on that before, although I've lately started thinking ghci> is pretty intuitive actually, and it's used by RWH.

I've suggested repl> as an alternative, since > is already taken by code blocks.

[ghc-mirror]

Original reporter: sol@

I was never really sure about ghci> and I like repl>. So for me it would just be fine to change that. Can we agree on repl>?

[ghc-mirror]

Original reporter: david.waern@

Replying to [comment:4 SimonHengel]:

I was never really sure about ghci> and I like repl>. So for me it would just be fine to change that. Can we agree on repl>?

Fine for me.

[ghc-mirror]

Original reporter: marlowsd@

repl> would look a bit weird if you didn't know what it stood for, and if you know what it stands for then it's clutter. Why not choose a generic prompt symbol, e.g. >>>, -->, or something?

[ghc-mirror]

Original reporter: david.waern@

Replying to [comment:6 simonmar]:

repl> would look a bit weird if you didn't know what it stood for, and if you know what it stands for then it's clutter. Why not choose a generic prompt symbol, e.g. >>>, -->, or something?

I'm OK with >>>.

Actually > could work as well if disambiguate between code blocks and examples based on the fact that all lines must start with > in code blocks but not in examples (IIRC). What do you think?

[ghc-mirror]

Original reporter: sol@

Replying to [comment:7 waern]:

Replying to [comment:6 simonmar]:

repl> would look a bit weird if you didn't know what it stood for, and if you know what it stands for then it's clutter. Why not choose a generic prompt symbol, e.g. >>>, -->, or something?

I'm OK with >>>.

What would we use for qc properties than? Still prop>?

[ghc-mirror]

Original reporter: marlowsd@

Replying to [comment:8 SimonHengel]:

What would we use for qc properties than? Still prop>?

Hmm, I forgot we have those too. prop> would be ok by me.