Controlling the documentation for reexported modules

[0xd34df00d]

I just found myself desiring to not reexport the documentation for a module that I'm reexporting but which I've imported with an explicit hiding list. Contrary to this, the issue #958 asks for an option to reexport the documentation for a module that has no explicit import/hiding list.

This sounds like there needs to be an option to control the general behaviour of haddock with respect to the reexported modules. Indeed, one might just have expand-reexported-modules (as #958 suggests) as well as hide-reexported-modules (for my use case), but one might want to have more fine-grained control over the exports, perhaps at the level of individual modules.

Something like

module Foo where
( foo
, bar
, module X {-# HADDOCK hide #-}
, module Y {-# HADDOCK show #-}
)

seems good enough for me off the top of my head.

What do you think?

In any case, I'd also be happy to hack on this (but beware this is going to be my first contribution to haddock and ghc ecosystem).

[harpocrates]

This has come up before. The problem with hide-reexported-modules as you describe it is that it isn't really honest, since not all of the modules contents are re-exported. To use your example, suppose you had:

module Foo where
( foo
, bar
, module X {-# HADDOCK hide #-}
, module Y {-# HADDOCK show #-}
)

import X hiding (baz)

Then, seeing just a link to module X in the generated Haddocks would mask the fact that not all things in X really are available (for instance: baz won't be).

The proposed expand-reexported-modules is a different matter: since the whole module is re-exported, inlining the documentation is just a matter of saving a click.

So:

• I 100% agree we need a better story around module re-exports.
• your proposed {-# HADDOCK hide #-}/{-# HADDOCK show #-} options are much more intuitive than some global file level switch, but also much more work than a global file-level switch
• in order to selectively collapse modules, we'd need to provide some extra information in the rendered Haddocks, hinting to the user that the whole module is not available.