[haddock] #140: Support for doctest style usage blocks

[haddock]

#140: Support for doctest style usage blocks
------------------------+---------------------------------------------------
Reporter:  ezyang       |       Owner:       
    Type:  enhancement  |      Status:  new  
Priority:  major        |   Milestone:  2.7.0
 Version:  2.6.0        |    Keywords:       
------------------------+---------------------------------------------------
 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 at haskell.org/msg39060.html

-- 
Ticket URL: <http://trac.haskell.org/haddock/ticket/140>
haddock <http://www.haskell.org/haddock>
Haddock, The Haskell Documentation Tool