2008/1/23, Ross Paterson
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