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...

I think it makes more sense to put the documentation in the module where the types are declared. Haddock will create doc files with the correct structure for you. For example, if you have module Foo which exports types A, B and C (with documentation) and module Bar which re-exports only A, then the doc files for Bar will automatically contain the relevant documentation for A, copied over from module Foo. — Chris Taylor
@ChrisTaylor I know it will work, it's just a little inelegant. I'll do it if there's no way around it, but I want to see if there's a better way first. — MathematicalOrchid
Seconding Chris Taylor. When people are reading your source, they are going to want the docs by the code; that's I think the whole point of mixing doc markup and code. Relevant tip I just learned: if you put some code in a non-exported sub-module and want to reference functions from another non-imported module from your project, you can give a full path, like 'Control.Foo.bar' and that will show up as a link with text "bar" — jberryman

dflemstr dflemstr · Accepted Answer · 2012-07-31T09:51:54

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

write different versions in different locations
have one version override another
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:

Haddock 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.

Haddock comments on imported entities

2 Answers