Re: [Haskell] ANNOUNCE: Haddock version 2.0.0.0

newer
darcs patch: Small documentation...

older
Re: [Haskell] ANNOUNCE: Haddock...

Ross Paterson

23 Jan 2008 23 Jan '08

10:12 a.m.

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

Show replies by date

David Waern

23 Jan 23 Jan

11:57 a.m.

New subject: [Haskell] ANNOUNCE: Haddock version 2.0.0.0

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

Ross Paterson

12:26 p.m.

New subject: [Haskell] ANNOUNCE: Haddock version 2.0.0.0

On Wed, Jan 23, 2008 at 05:57:18PM +0100, David Waern wrote:

...

2008/1/23, Ross Paterson :

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

That one is a show-stopper for HackageDB.

...

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

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

Some examples of things people do that were harmless before: -- | module header -- | extra comment describing module module MyModule where import Stuff -- ^ we might use this type MyInt = Int -- ^ comment

David Waern

1:10 p.m.

New subject: [Haskell] ANNOUNCE: Haddock version 2.0.0.0

2008/1/23, Ross Paterson :

...

On Wed, Jan 23, 2008 at 05:57:18PM +0100, David Waern wrote:

...
2008/1/23, Ross Paterson :

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

That one is a show-stopper for HackageDB.

Right, we have to prioritize this one.

...

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

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

Some examples of things people do that were harmless before:

-- | module header

-- | extra comment describing module module MyModule where

import Stuff -- ^ we might use this

type MyInt = Int -- ^ comment

I've added this as a bug to TODO, but I'm not sure how to fix it easily. David

David Waern

10 Feb 10 Feb

4:35 p.m.

New subject: [Haskell] ANNOUNCE: Haddock version 2.0.0.0

2008/1/23, David Waern :

...

2008/1/23, Ross Paterson :

...
On Wed, Jan 23, 2008 at 05:57:18PM +0100, David Waern wrote:

...
2008/1/23, Ross Paterson :

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

That one is a show-stopper for HackageDB.

Right, we have to prioritize this one.

I've now fixed this issue - a patch is available in the darcs repository.

...

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

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

Some examples of things people do that were harmless before:

-- | module header

-- | extra comment describing module module MyModule where

import Stuff -- ^ we might use this

type MyInt = Int -- ^ comment

I've tried these examples with Haddock 0.9 and it only accepts the last one. That's a regression in Haddock 2. But the other examples don't seem to be regressions. David

Ross Paterson

13 Feb 13 Feb

8:05 a.m.

New subject: [Haskell] ANNOUNCE: Haddock version 2.0.0.0

On Sun, Feb 10, 2008 at 10:35:28PM +0100, David Waern wrote:

...

2008/1/23, David Waern :

...
...
...
2008/1/23, Ross Paterson :

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

I've now fixed this issue - a patch is available in the darcs repository.

OK, that seems to be fine now. If you build the libraries in ghc-6.8.2 (with the added OPTIONS_HADDOCK pragmas) with haddock-2.1, Data-Array.html is almost empty. The old Haddock had problems with re-exports from another package: * re-exported functions/types/classes were just shown as hyperlinked names without docs (the docs aren't stored in the interface file) * re-exported modules weren't shown at all (no reason that I can think of). However the new haddock doesn't even show the re-exported names.

David Waern

8:20 a.m.

New subject: [Haskell] ANNOUNCE: Haddock version 2.0.0.0

2008/2/13, Ross Paterson :

...

...
2008/1/23, David Waern :

...
...
...
2008/1/23, Ross Paterson :

...
If I add the new-style attributes to the base package, it hides

On Sun, Feb 10, 2008 at 10:35:28PM +0100, David Waern wrote: 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.

I've now fixed this issue - a patch is available in the darcs repository.

OK, that seems to be fine now.

If you build the libraries in ghc-6.8.2 (with the added OPTIONS_HADDOCK pragmas) with haddock-2.1, Data-Array.html is almost empty. The old Haddock had problems with re-exports from another package:

* re-exported functions/types/classes were just shown as hyperlinked names without docs (the docs aren't stored in the interface file) * re-exported modules weren't shown at all (no reason that I can think of).

However the new haddock doesn't even show the re-exported names.

Oh, interesting. We should be able show the docs for re-exports, since the new Haddock do store them in the interface files. Thanks for the report, David

Ross Paterson

8:38 a.m.

New subject: [Haskell] ANNOUNCE: Haddock version 2.0.0.0

On Wed, Feb 13, 2008 at 02:20:00PM +0100, David Waern wrote:

...

Oh, interesting. We should be able show the docs for re-exports, since the new Haddock do store them in the interface files.

That's wonderful news. cf the complaint about Data.Array on haskell-cafe: the functions have fine documentation, but it's all in the base package and so isn't being shown.

David Waern

10 Feb 10 Feb

9:07 a.m.

New subject: [Haskell] ANNOUNCE: Haddock version 2.0.0.0

2008/1/23, Ross Paterson :

...

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

I just took a look a this last issue. It is not a bug, Haddock has never supported doc comments that are attached to the arguments of a non-record constructor. David

6307

Age (days ago)

6328

Last active (days ago)

List overview

Download

8 comments

2 participants

participants (2)

David Waern
Ross Paterson

Re: [Haskell] ANNOUNCE: Haddock version 2.0.0.0

tags

participants (2)