Haddock comments on imported entities

Question

Is there a way to add Haddock documentation to an entity in the module which exports it, rather than the one that declares it?

I've got a hidden module that declares a dozen types or so, and then another module which exports just the parts that the end-user is supposed to see. It would be logical to put the documentation in the exposed module rather than the hidden one. But I can't figure out how to do that...

Answer 1

No, it's not possible. Functions can have per-argument and per-type-param documentation, and it would make documentation inconsistent if you could:

1. write different versions in different locations
2. have one version override another
3. introduce inconsistencies in argument documentation: what if you override the main doc string for a function; should the argument doc strings be removed?

The following file:

module Bla
       ( -- * Fooishness

         -- | This is 'foo'. It is not 'bar'.
         foo
       , -- * Barishness

         -- | This is 'bar'. It is sometimes a little 'foo'.
         bar
       ) where

-- | The actual foo documentation
foo :: a -- ^ The a
    -> b -- ^ The b
    -> c
foo = undefined

-- | The actual bar documentation
bar :: a
bar = undefined

...yields this documentation:

As you can see, you can use section comments to kind of emulate function documentation strings, but the documentation will only be properly generated if you use function documentation comments right by the type signatures.

Answer 2

Well, come to think of it, I could write a newtype in the exposed module. It carries no run-time overhead, it just makes my code a little more messy...