Ticket #140 (closed enhancement: fixed)
Support for doctest style usage blocks
|Reported by:||ezyang||Owned by:|
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://email@example.com/msg39060.html