Question

What is literate programming? To quote Dr. Knuth:
“The main idea is to regard a program as a communication to human beings rather than as a set of instructions to a computer.”

What are the popular ways to generate haskell application project documentation? Please mention main strength area / key benefits of each method.

Answer 1

The most common way is to use Haddock markup.

To do this you start a comment line with -- |. The documentation continues until the next non-comment line:

-- |This is a doc comment
--  which continues onto the next line.

If you want to generate links to other parts of the documentation, use single quotes around function names. If you want to specify fixed-width font, enclose text within @ symbols. If you want to specify a code block, start a comment line with -- >.

Here’s a real-world example taken from the GHC Base source code, which compiles into the documentation seen on this page.

-- | 'map' @f xs@ is the list obtained by applying @f@ to each element
-- of @xs@, i.e.,
--
-- > map f [x1, x2, ..., xn] == [f x1, f x2, ..., f xn]
-- > map f [x1, x2, ...] == [f x1, f x2, ...]

map :: (a -> b) -> [a] -> [b]
map _ []     = []
map f (x:xs) = f x : map f xs