haddock discussion: Add option to hide definitions of given types
We intend to stop Cabal from passing -DHADDOCK_VERSION
when compiling haddocks (see https://github.com/haskell/cabal/pull/9177).
The most legitimate use of HADDOCK_VERSION
out there is haskell-gi
, which uses HADDOCK_VERSION
to omit generating AttrLabelProxy
top-level definitions for use with OverloadedLabels
, such as in:
terminalAllowBold :: AttrLabelProxy "allowBold"
where
-- | A proxy for attribute labels.
data AttrLabelProxy (a :: Symbol) = AttrLabelProxy
instance a ~ x => IsLabel x (AttrLabelProxy a) where
fromLabel = AttrLabelProxy
It is a bit controversial whether it's a good idea to omit certain definitions from the haddocks.
I'm opening this ticket to track a discussion for a feature built-in to haddock to explicitly omit definitions of a certain type (in this case AttrLabelProxy
).
@michaelpj suggests a per-definition {-# HADDOCK_OMIT #-}
pragma which could hide any particular definition. I agree that this would be more principled and more useful than any type-directed solution. This fits the haskell-gi
case too.