Haddock: Failed to create dependency graph (when adding sections with * or a module heading)

Question

I compiled and installed haddock-2.4.2 from the tarball source.

Adding a few simple comments to the code here:

• https://dl.getdropbox.com/u/143480/doc/DualMap.hs

and running haddock

$ haddock -h -o doc Data/DualMap.hs
Warning: Data.DualMap: could not find link destinations for:
    Data.Typeable.Typeable2 GHC.Base.Eq GHC.Show.Show GHC.Base.Ord GHC.Base.Bool Data.Set.Set

yields:

• https://dl.getdropbox.com/u/143480/doc/Data-DualMap.html

Things look good. (Note that this module only depends on libs that ship with GHC and no other source modules.)

However, when I try to add sections (a la http://www.haskell.org/haddock/doc/html/ch03s04.html#id289234 ) in the comments with "-- * test" I get:

$ haddock -h -o doc Data/DualMap.hs
Data/DualMap.hs:20:0: parse error on input `-- * test'
haddock: Failed to create dependency graph

I have no idea where to begin getting this to work since this error message only tells me that Haddock.Interface.depanal returned Nothing (according to a grep of the haddock sources) but not how to stop the dependency analysis from failing. Perhaps I need some more command line arguments or references to missing link destinations in GHC/base/containers documentation or some haddock config file?

Searching Google yielded plenty of cabal build errors of the same ilk for packages on hackage but nothing about how to fix them.

How do I add sections (with asterisks) and get Haddock to generate my docs? What (probably simple thing) am I missing?

Answer 1

Simple fix (terrible error message):

Move the ( up to the line with the module name. Previous bad code:

module Data.DualMap
   -- * The @DualMap@ abstract type
   ( DualMap ()
   -- * (?) internal? -- exposed for testing purposes, for now...
   , dmFlip
   -- * converting to and from DualMap
   , toList, fromList, map
   -- * constructing a DualMap
   , empty, null, insert, union

Happy code looks like this:

module Data.DualMap (
   -- * The @DualMap@ abstract type                                                                                                                                 
     DualMap ()
   -- * (?) internal? -- exposed for testing purposes, for now...                                                                                                   
   , dmFlip
   -- * converting to and from DualMap                                                                                                                              
   , toList, fromList, map
   -- * constructing a DualMap                                                                                                                                      
   , empty, null, insert, union

Simple enough. I found this out by downloading DList from hacakge and gutting it and replacing the code with my own code. When DList worked with 'cabal haddock' and mine didn't (when I tried to add some asterisks), I looked at the difference between the files and sure enough my parenthesis was on the wrong line.

BTW I highly recommend DList as a starting place for a new Haskell project instead of hnop.