0

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.

lesolorzanov
  • 3,536
  • 8
  • 35
  • 53
  • Er, `cabal haddock` and done? — This question asks some rather different things, I think you should narrow it down to one subject lest it be closed as too broad. – leftaroundabout Feb 28 '17 at 13:35
  • @leftaroundabout It is not just that. I tried and it only created one link to the main package I want a list of functions contained in the program like when I do :bro in ghci. Also I would like to know where to dd this command in the setup file so that it is generated instead of me having to call cabal for each command individually. It is not that trivial. And I'd say there are very poor and few examples on comment syntax to generate documentation. – lesolorzanov Feb 28 '17 at 14:36
  • Ah, now I see what's the issue (this is actually about module exports). Please edit so the answers can actually match the question, not just the comment to the question... – leftaroundabout Feb 28 '17 at 14:44
  • I am new to haskell so I am not familiar with terminology. I understan there is a main module, but I dont need it in the documentation. I have very simple files which dont even contain classes, just some types and functions, I don't know if I can document those. Can you help me rephrase the question? – lesolorzanov Feb 28 '17 at 14:47

1 Answers1

3

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.

leftaroundabout
  • 117,950
  • 5
  • 174
  • 319