Haddock: Falha ao criar gráfico de dependência (ao adicionar seções com * ou um título de módulo)

Question

Compilei e instalei o Haddock-2.4.2 da fonte de tarball.

Adicionando alguns comentários simples ao código aqui:

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

e correndo 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

rendimentos:

• https://dl.getdropbox.com/u/143480/doc/data-dualmap.html

As coisas parecem boas. (Observe que este módulo depende apenas de Libs que enviam com GHC e nenhum outro módulo de origem.)

No entanto, quando tento adicionar seções (a la http://www.haskell.org/haddock/doc/html/ch03s04.html#id289234 ) Nos comentários com "- * teste", eu recebo:

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

Não tenho idéia de onde começar a fazer isso funcionar, pois essa mensagem de erro só me diz que haddock.interface.depanal não retornou nada (de acordo com um grep das fontes de haddock), mas não como impedir que a análise de dependência falhe. Talvez eu precise de mais alguns argumentos da linha de comando ou referências aos destinos de link ausentes na documentação do GHC/base/contêineres ou em algum arquivo de configuração de haddock?

A pesquisa do Google produziu muitos erros de construção da CABAL da mesma forma para pacotes em hackage, mas nada sobre como corrigi -los.

Como adiciono seções (com asteriscos) e faço que o Haddock gere meus documentos? O que (provavelmente simples) estou perdendo?

Answer 1

Correção simples (mensagem de erro terrível):

Mova o (até a linha com o nome do módulo. Código ruim anterior:

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

Código feliz se parece com o seguinte:

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

Simples o suficiente. Eu descobri isso baixando DList de Hacakge e estripando -o e substituindo o código pelo meu próprio código. Quando o DLIST trabalhou com 'Cabal Haddock' e o meu não (quando tentei adicionar alguns asteriscos), olhei para a diferença entre os arquivos e com certeza que meu parêntese estava na linha errada.

Btw eu recomendo o DLIST como um ponto de partida para um novo projeto Haskell em vez de hnop.