Data.Array documentation utterly broken

[japple]

http://www.haskell.org/ghc/docs/latest/html/libraries/array/Data-Array.html

vs

http://www.haskell.org/ghc/docs/6.6-latest/html/libraries/base/Data-Array.html

[igloo]

Thanks for the heads-up, we'll look into what's going on.

[igloo]

I think that the problem is that haddock would be able to see the docs (which live in base:GHC.Arr) when compiling base:Data.Array, but now that it compiles array:Data.Array it can no longer see them.

We should fix this somehow if possible; one way might be to just move GHC.Array into the array package; I don't know how feasible that is.

[simonmar]

Haddock 2 will fix this, as I understand it.

[japple]

Haddock 2 will fix this, as I understand it.

Actually, it seems even worse. See  http://code.haskell.org/~fons/libraries.html-haddock2.tgz, found at ticket:2299.

[ross]

We really need a bug tracker for Haddock2.

[igloo]

See also #1269

[igloo]

This is  http://trac.haskell.org/haddock/ticket/24

[japple]

We should not wait for Haddock to be fixed to get this fixed. If Haddock can't generate the proper documentation for symbols exported from another package, the GHC documentation should be generated from the appropriate package.

If the main repository for documentation of the standard library does not document how arrays are used, I would venture to say that your language does not really support arrays.

[japple]

I mean "one's language", not "your language".

[simonmar]

A quick fix for 6.10.1 would be to un-hide GHC.Arr, then at least we'd get hyperlinks in the Data.Array docs that would take you to the actual documentation.

[waern]

We should make Haddock document re-exports from other packages properly. For this to work, GHC needs to provide Binary instances for LHsDecl and the types it contains. It would also be nice if it provided instances for HsDoc and HaddockModInfo which Haddock currently defines itself. We need the Binary instances so we can store the declarations and doc comments in the .haddock files.

[igloo]

I'll fix this with copy/paste in the 6.10 branch.

[igloo]

Hmm, not so simple. I've just unhidden GHC.Arr in the 6.10 branch. Unfortunately, we can't link there from Data.Array due to  http://trac.haskell.org/haddock/ticket/13

[simonmar]

That Haddock bug only applies to references to modules from inside documentation, so the hyperlinks for the actual names should still work, right? Also, could we do something like this:

module Data.Array where
import qualified GHC.Arr

-- | .. documentation for 'array'
array = GHC.Arr.array

only works for functions, of course.

[igloo]

Replying to simonmar:

That Haddock bug only applies to references to modules from inside documentation, so the hyperlinks for the actual names should still work, right?

Yes. I was trying to say "Look in GHC.Arr for docs".

Also, could we do something like this: {{{ module Data.Array where import qualified GHC.Arr -- | .. documentation for 'array' array = GHC.Arr.array }}} only works for functions, of course.

Also, if GHC.Arr.array and Data.Array.array are both in scope then you have an ambiguous variable.

But links to array in the docs go to GHC.Arr now, so it's only people browsing to the Data.Array docs who will have the inconvenience of having to manually browse to the GHC.Arr docs.

It's not a perfect situation, but I think it's good enough for now.

[waern]

Re-exported names now appear in the documentation for Data.Array (#2746 fixed). However, there are no links to the original module GHC.Arr since it is hidden (in the Haddock sense of the word). So while waiting for Haddock to fully document re-exports from other packages, we could perhaps un-hide this module or export the declarations from another non-hidden module in base.

[simonmar]

Replying to waern:

Re-exported names now appear in the documentation for Data.Array (#2746 fixed). However, there are no links to the original module GHC.Arr since it is hidden (in the Haddock sense of the word). So while waiting for Haddock to fully document re-exports from other packages, we could perhaps un-hide this module or export the declarations from another non-hidden module in base.

GHC.Arr is not hidden in the GHC 6.10 branch, as a workaround for exactly this. Maybe we should un-hide it in the HEAD too, with a comment to explain why, to avoid future confusion.

BTW David - thanks for all your work on fixing Haddock recently, it's much appreciated!

[isaacdupree]

So, this should be fixed with Haddock HEAD, as soon as we decide it's stable enough to release... not for a few days at least :-), but pretty surely before the GHC RC

[simonmar]

Now fixed, mainly thanks to isaacdupree's SoC patches, and also thanks to David's subsequent fixes.