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.
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 wrimchTransmogrify 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.