From: haskell-cafe-bounces@haskell.org [mailto:haskell-cafe-bounces@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. *****************************************************************