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