[Haskell-cafe] Haddock and literate Haskell: annotations must be marked as source?

[Andy Gimblett]

Hi all,

I've developed a bit of a taste for literate Haskell lately, being a  
verbose sort of guy.  Unfortunately, it doesn't seem to interact with  
Haddock in the way I'd like/expect.  I just wanted to check that my  
understanding of the situation is correct before I (regretfully) give  
up on LHS.

It seems to me that Haddock only picks up annotation comments (ie  
those that should be included in the produced documentation) from  
literate Haskell source when those annotations are themselves marked  
up as source - it seems not to recognise them in the general text.

For example, I was expecting/hoping that from the point of view of  
Haddock, the following literate Haskell code with an annotation-marked  
paragraph (starts with a vertical bar) in the non-source text.

| Turn a foo into a bar.

 > foo :: Foo -> Bar
 > foo b = ...

ought to be equivalent to the following "illiterate" Haskell:

-- | Turn a foo into a bar.
foo :: Foo -> Bar
foo b = ...

ie, it should produce Haddock docs where the definition of foo is  
annotated with that comment.

Sadly, that appears not to be the case.  It appears the literate  
version needs to look like this:

 > -- | Turn a foo into a bar
 > foo :: Foo -> Bar
 > foo b = ...

which to my mind rather defeats the purpose of being literate.

So: am I right that this is the intended/expected behaviour?  If not,  
how does one get round it?  If so, could someone perhaps comment on  
the prospects/complexity of implementing this - or the reasons why it  
is in fact a bad idea?

Many thanks!

-Andy