Good Haskell Style

[Alistair Bayley]

> > I moot that birdtrack-literate-haskell should be avoided, largely
> > because (AFAICT) it is not supported by Haddock.
>
> Doesn't Cabal handle this transparently? I thought it did. If you find
> it doesn't please file a bug against Cabal.
>
> Duncan

I didn't think it would work, because presumably it just invokes Haddock anyway.

So I just tried it, and got:
dist\build\tmp\Database\Enumerator.hs:"dist\\build\\tmp\\Database\\Enumerator.hs":
187:1: Parse error

and the offending lines in this file are:

#ifndef __HADDOCK__
    deriving (Functor, Monad, MonadIO, MonadFix, MonadReader sess)
#else
    -- Haddock can't cope with the "MonadReader sess" instance
    deriving (Functor, Monad, MonadIO, MonadFix)
#endif

so it would appear that __HADDOCK__ is not defined. But there's a
bigger problem, in that this Enumerator.hs file is obviously the
output of "ghc -E Enumerator.lhs -o Enumerator.hs", as it does not
contain any of the original comments, which again is no good for
Haddock.

Am I using birdtrack-lhs the wrong way? I've written my Haddock
comments like so:

| Returns the number of rows affected.

> execDML :: IE.Command stmt s => stmt -> DBM mark s Int

and:

|
Module      :  Database.Enumerator
Copyright   :  (c) 2004 Oleg Kiselyov, Alistair Bayley
License     :  BSD-style
...

But now I'm thinking that perhaps I should have written:

> --| Returns the number of rows affected.
> execDML :: IE.Command stmt s => stmt -> DBM mark s Int

which kinda defeats the purpose of the birdtrack style.IMO.

Alistair