Conditional code for Haddock
I want to generate documentation for the following code snippet:
import qualified Data.ByteString as BS ( ByteString, length )
-- | Foo 'BS.empty' equals 0 foo ∷ BS.ByteString → Int foo = BS.length
Because I do not explicitly import BS.empty haddock will not generate a nice link. I can fix it by adding:
import qualified Data.ByteString as BS ( empty )
But now the compiler rightly warns me:
Warning: Imported from `Data.ByteString' but not used: `BS.empty'
There is a ticket related to this problem [1], but I do not think making haddock 'magically' find BS.empty is the right answer. What I would like to do is:
#ifdef __DOC__ import qualified Data.ByteString as BS ( empty ) #endif
Because I use additional symbols in my comments it feels natural to also have special imports for them. I know that cabal used to define the __HADDOCK__ macro. Is it possible to manually define a preprocessor macro when haddock is run? Perhaps an equivalent to ghc-options: haddock-options? Ideally I want only have to add the following to my .cabal file:
haddock-options: -D__DOC__
Regards, Roel van Dijk 1 - http://trac.haskell.org/haddock/ticket/78
Am Mittwoch 20 Januar 2010 12:20:55 schrieb Roel van Dijk:
I want to generate documentation for the following code snippet:
import qualified Data.ByteString as BS ( ByteString, length )
-- | Foo 'BS.empty' equals 0 foo ∷ BS.ByteString → Int foo = BS.length
Because I do not explicitly import BS.empty haddock will not generate a nice link.
I can fix it by adding:
import qualified Data.ByteString as BS ( empty )
But now the compiler rightly warns me:
Warning: Imported from `Data.ByteString' but not used: `BS.empty'
There is a ticket related to this problem [1], but I do not think making haddock 'magically' find BS.empty is the right answer. What I would like to
do is:
#ifdef __DOC__ import qualified Data.ByteString as BS ( empty ) #endif
Because I use additional symbols in my comments it feels natural to also have special imports for them.
I know that cabal used to define the __HADDOCK__ macro. Is it possible to manually define a preprocessor macro when haddock is run? Perhaps an equivalent to ghc-options: haddock-options?
Doesn't haddock define __HADDOCK__ by itself? I would've thought import qualified Data.ByteString as Bs ( ByteString , length #ifdef __HADDOCK__ , empty #endif ) should work.
Ideally I want only have to add the following to my .cabal file:
haddock-options: -D__DOC__
Regards, Roel van Dijk
Doesn't haddock define __HADDOCK__ by itself?
I would've thought
import qualified Data.ByteString as Bs ( ByteString , length #ifdef __HADDOCK__ , empty #endif )
should work.
I did some conditional Haddocking in EMGM. See, for example: http://hackage.haskell.org/packages/archive/emgm/0.3.1/doc/html/src/Generics... Sean
On Wed, Jan 20, 2010 at 12:57 PM, Sean Leather
I did some conditional Haddocking in EMGM. See, for example: http://hackage.haskell.org/packages/archive/emgm/0.3.1/doc/html/src/Generics...
At first I didn't see what you did differently. Until I checked your Setup.lhs. It does exactly what I want! Plus a few other things which I am going to borrow (runtests hook, nolib flag and hpc program coverage). Thank you.
On Wed, Jan 20, 2010 at 16:17, Roel van Dijk wrote:
On Wed, Jan 20, 2010 at 12:57 PM, Sean Leather wrote:
I did some conditional Haddocking in EMGM. See, for example:
http://hackage.haskell.org/packages/archive/emgm/0.3.1/doc/html/src/Generics...
At first I didn't see what you did differently. Until I checked your Setup.lhs. It does exactly what I want! Plus a few other things which I am going to borrow (runtests hook, nolib flag and hpc program coverage).
I'm glad somebody else can make use of that stuff. Regards, Sean
Doesn't haddock define __HADDOCK__ by itself?
That appears to be a common misconception. The discussion on this ticket [1] indicates that haddock does *not* define __HADDOCK__. So I can not rely on it being defined. Therefore I would like to define it myself, but only in the case that haddock is being run on my code. 1 - http://trac.haskell.org/haddock/ticket/76
participants (3)
-
Daniel Fischer -
Roel van Dijk -
Sean Leather