Question

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?

Answer 1

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.