[Haskell] ANNOUNCE: Haddock version

Ross Paterson ross at soi.city.ac.uk
Wed Jan 23 10:12:12 EST 2008

On Tue, Jan 08, 2008 at 01:28:50PM +0100, David Waern wrote:
>   * Format of module attributes has changed. The only way of specifiying
>     module attributes is via a new OPTIONS_HADDOCK pragma. Example:
>     {-# OPTIONS_HADDOCK hide, prune #-}

Unfortunately the old-style attributes are widely used: over 400 modules
in hackage, including 100 shipped with GHC.  The vast majority of these
are #hide, which ideally should be unnecessary if the modules are not
exposed.  However some packages expose modules for use in the internals of
other packages, but don't want to show those modules in the documentation.
For example, most of the GHC.* modules in the base package, which are used
in the internals of many of the packages split from base.

If I add the new-style attributes to the base package, it hides those
modules in the documentation for base, but packages that depend on base
seem to generate links to locations in those hidden modules, e.g. uses
of IO point at GHC.IOBase.IO.

Also, the new haddock rejects some modules the old one accepted.
For example, it doesn't like extra doc comments that aren't attached
to anything.  It also rejects

  data Pair = Pair {-# UNPACK #-} !Int -- ^ first field
                   {-# UNPACK #-} !Int -- ^ second field

More information about the Libraries mailing list