Changing the documentation for re-exported types and values

Question

Suppose I have a module which re-exports a value from an internal module:

module My.Cool.Module (SomeType, someValue) where
import My.Cool.Module.Internal (SomeType, someValue)

I'd like to show different documentation for SomeType and someValue in My-Cool-Module.html and My-Cool-Module-Internal.html, so the former can discuss the public API and the latter can discuss how they relate to the rest of internals.

Is there a way to do this with haddock?

I tried:

module My.Cool.Module (SomeType, someValue) where
import My.Cool.Module.Internal
  ( SomeType -- ^ a serious type for serious people
  , someValue -- ^ a serious value for serious people
  )

But haddock gave me a parse error:

parse error on input ‘-- ^ a serious type for serious people’

Answer 1

Ok, here's a hack that I can live with.

Haddock allows you to insert named chunks of documentation, which are shown in the order they're defined. These named chunks are only shown for the module they're in, not in any file that re-exports values or types from that module.

So in the internal module, I can insert named chunks containing the internal documentation right after the public API documentation:

-- | Have you welcomed internal modules into your life?
module Public.Private where

-- | Here's the public API information for 'SomeType'
type SomeType = ()
-- $
-- Here's the internal information about 'SomeType': it's really just a stand-in
-- for San Francisco

-- | Here's the public API information for 'someValue'
someValue :: SomeType
-- $ Here's the internal information about 'someValue': it loves cheese.
someValue = ()

and then export the types and values as normal

-- | This is a very serious public API
module Public ( SomeType, someValue) where
import Public.Private ( SomeType , someValue)

Now the generated documentation for Public.Private shows the internal documentation right after the public documentation:

While the Public documentation for the exported items doesn't show the internal documentation:

This only allows me to append private documentation, but that's better than nothing.