Hiding declaration of type synonym in Haddock

Question

I'm writing a library, and in it I have defined and exported some (very convoluted) type synonym T.

-- | A type
type T a b i o = ReaderT (WriterT i a X) (WriterT i b o)

Internal to the library, the type makes sense. To a user, however, it is unecessary and confusing. For that reason, I would prefer to hide the actual declaration of the type in the Haddock page.

I.E., I would prefer the Haddock page look like this...

type T a b i o
    A type

... rather than this.

type T a b i o = ReaderT (WriterT i a X) (WriterT i b o)
    A type

Is this possible? If so, how?

Answer 1

If your users really don't need to know what's under the hood, you should use a newtype and not export the constructor. GeneralizedNewtypeDeriving can help ease the pain of this approach. If some of your users may want to peek behind the curtain, you can expose the newtype constructor from a base module but hide it from the main module. Type synonyms are a very weak tool for abstraction in general. The lens library uses them to good effect, to allow packages to define lenses without depending on lens, but that's a bit of an oddball.

I don't think there's any way to tell Haddock to hide what a type synonym means. That doesn't, however, mean you can't do what you want.

Cabal defines the __HADDOCK_VERSION__ CPP macro when documentation is being built. If you're so inclined, you can detect this and replace the type synonym with a newtype. This wouldn't compile, of course, but I don't think it should cause Haddock any trouble. I don't think this is at all wise, though.