Open 0xd34df00d opened 4 years ago
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:
{-# 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
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 ashide-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
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).