[Haskell] ANNOUNCE: Haddock version 2.0.0.0

[David Waern]

2008/1/23, Ross Paterson <ross at soi.city.ac.uk>:
> 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.

I actually added support for old-style attributes to GHC so that most
packages wouldn't need updating, but unfortunately that patch didn't
make it into 6.8.2. I agree that Haddock should use the
exposed-packages field from Cabal, and that it would work for most
packages. For the packages that still need explicit attributes, we can
either update them manually, or perhaps beg for my patch to be
included in 6.8.3.

> 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.

That's definitely a bug, I'm adding it to the TODO file.

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

Hmm, it is possible that the parser has (accidentally) become a bit stricter.

> It also rejects
>
>   data Pair = Pair {-# UNPACK #-} !Int -- ^ first field
>                    {-# UNPACK #-} !Int -- ^ second field

Ah, yes, this has been reported before but it hasn't been investigated yet.

Thanks for the feedback, it is much appreciated.

David