2

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

MathematicalOrchid
  • 61,854
  • 19
  • 123
  • 220
  • 1
    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 Jul 31 '12 at 09:50
  • @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 Jul 31 '12 at 09:51
  • 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 Jul 31 '12 at 15:14

2 Answers2

5

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:

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.

dflemstr
  • 25,947
  • 5
  • 70
  • 105
  • To be clear: I'm not trying to write different documentation for the same entity. I just want to put all the documentation in one file, the exposed module, because that feels more logical. I know Haddock has a way to adjust the "home module" for an entity, I wasn't sure if that might let me do something... – MathematicalOrchid Jul 31 '12 at 09:56
0

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

MathematicalOrchid
  • 61,854
  • 19
  • 123
  • 220