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

[Bayley, Alistair]

> From: haskell-cafe-bounces at haskell.org 
> [mailto:haskell-cafe-bounces at haskell.org] On Behalf Of Andy Gimblett
> 
> 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.
> 
> 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?  


Haddock currently uses ghc's parser, and I believe the literate preprocessor discards comments. I think there is an item on the haddock wishlist to preserve the literate comments, but I'm not certain...

This problem has been solved in cabal, BTW. Cabal preprocesses .lhs itself, rather than trust the compiler to do it, and it preserves the comments. If you generate you haddocks with cabal, then you should be able to use the markup the way you expected.

The Takusen source files are written in this style. For example, see:
 http://darcs.haskell.org/takusen/Database/Enumerator.lhs

Alistair
*****************************************************************
Confidentiality Note: The information contained in this message,
and any attachments, may contain confidential and/or privileged
material. It is intended solely for the person(s) or entity to
which it is addressed. Any review, retransmission, dissemination,
or taking of any action in reliance upon this information by
persons or entities other than the intended recipient(s) is
prohibited. If you received this in error, please contact the
sender and delete the material from any computer.
*****************************************************************