id,summary,reporter,owner,description,type,status,priority,milestone,version,resolution,keywords,cc
140,Support for doctest style usage blocks,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 [http://docs.python.org/library/doctest.html Python's doctest documentation]. Since Haskell does not normally support ""eval"", [http://hackage.haskell.org/package/hint 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",enhancement,closed,major,,2.6.0,fixed,,