Ticket #140 (closed enhancement: fixed)

Opened 4 years ago

Last modified 22 months ago

Support for doctest style usage blocks

Reported by: ezyang Owned by:
Priority: major Milestone:
Version: 2.6.0 Keywords:
Cc:

Description

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

Change History

  Changed 4 years ago by waern

  • milestone changed from 2.7.0 to 2.8.0

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.

  Changed 4 years ago by tibbe

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

  Changed 4 years ago by 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.

follow-up: ↓ 5   Changed 4 years ago by 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>?

in reply to: ↑ 4   Changed 4 years ago by waern

Replying to 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.

follow-up: ↓ 7   Changed 4 years ago by 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?

in reply to: ↑ 6 ; follow-up: ↓ 8   Changed 4 years ago by waern

Replying to 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?

in reply to: ↑ 7 ; follow-up: ↓ 9   Changed 4 years ago by SimonHengel

Replying to waern:

Replying to 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> ?

in reply to: ↑ 8   Changed 4 years ago by simonmar

Replying to SimonHengel:

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

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

  Changed 2 years ago by SimonHengel

  • status changed from new to closed
  • resolution set to fixed

  Changed 22 months ago by anonymous

  • milestone 2.8.0 deleted

Milestone 2.8.0 deleted

Note: See TracTickets for help on using tickets.