Suppose I have a library packaged and built using Cabal, and some module Internal is not in my cabal file's Exposed-modules. Does it then make any difference if I specify a pragma
{-# OPTIONS_HADDOCK hide #-}
at the top of Internal.hs, or is it already automatically hidden according to Haddock?
If it does make a difference, what effect does it have?
It does make a difference if the haddocks of the package are created with the --internal flag to cabal haddock.
$ cabal help haddock
Usage: cabal haddock [FLAGS]
Flags for haddock:
-h --help Show this help text
-v --verbose[=n] Control verbosity (n is 0--3, default verbosity
level is 1)
<snip>
--executables Run haddock for Executables targets
--internal Run haddock for internal modules and include all
symbols
<snip>
If the haddocks are created without the --internal flag, the hide module attribute has no effect: no documentation is created for the module anyway.
If --internal is given, then documentation is created for non-exposed modules except those that specify the hide attribute.
In other words, documentation is generated if hide is not set and either --internal is specified or the module is exported.
The use of --internal for cabal haddock can be specified with cabal install --haddock-internal, or when manually invoking cabal haddock, or with the runhaskell ./Setup.hs ... interface.
Most people just run cabal install with the default options, so only few would observe the difference.