Haskell haddock automatic documentation

Question

I have not been able to generate documentaion for haskell using haddock.

So far I have not found any useful examples. The documentation has a lot of options and also I am not sure about the comment syntax so that documentation is correctly generated.

I know that inside ghci I can call :bro for loaded files and it lists types and functions, I wish these functions could be documented with haddock even without comments. I don't know if this is possible.

Answer 1

If you build an executable, like

module Main (main) -- this line is implicit if your module isn't named otherwise
   where

-- | Some important function that does most of the work
foo :: Bar -> Baz
foo = ...

-- Other definitions
-- ...

-- | The program you want to run.
main :: IO ()
main = ...

-- ...

then Haddock assumes there's nothing public to actually document – after all, main is the only thing someone using that project actually gets to call, everything else is hidden!

To generate also documentation for foo, you need to export it, either directly from the Main module or from another module where it's originally defined. The usual way to go is to put everything really interesting in some “internal” modules, like

module Foo (foo, {- other stuff ... -}) where

-- | Some important function that does most of the work
foo :: Bar -> Baz
foo = ...

-- Other definitions
-- ... but not `main`

and for the executable only use an “end user scratch-resistant plastic wrapper” module

module Main (main) where

import Foo

main :: IO ()
main = ...

Then the documentation for Foo will contain the actually interesting Haskell API Haddocks. This will then look like

Foo

foo :: Bar -> Baz
Some important function that does most of the work

Actually, you'll want to write the documentation something like

-- | Transmogrify a bare bar into a zapcutted one
foo :: Bar -- ^ The bare input to transmogrify
    -> Baz -- ^ The zapcutted wrimch

yielding documentation looking like

Foo

foo ::

• Bar The bare input to transmogrify

• -> Baz The zapcutted wrimch

Transmogrify a bare bar into a zapcutted one

The Haddock for Main isn't really interesting, you might better put the information in some command-line help box.

In the project.cabal file, you then need to classify Foo as belonging to the “library” part of the project, whereas Main is the executable part.

Basically, Haddock is just for libraries, not for executables.