Support reexported-modules #563

Open
Profpatsch opened this Issue Dec 23, 2016 · 9 comments

Projects

None yet

3 participants

@Profpatsch
Profpatsch commented Dec 23, 2016 edited

It would be nice if Haddock could handle the reexported-modules list, otherwise those are not shown at all.

For example, ghcjs-dom reexports modules from its dependencies, but no documentation is generated at all:
https://hackage.haskell.org/package/ghcjs-dom

Similarly, ghcjs-dom-jsffi reexports and renames said modules, those are then used (and reexported) by ghcjs-dom again:
https://hackage.haskell.org/package/ghcjs-dom-jsffi-0.7.0.1/ghcjs-dom-jsffi.cabal

Also, the documentation is broken in that case (ghcjs-dom references the renamed modules internally).

@ezyang
Contributor
ezyang commented Dec 23, 2016

Agreed with @Profpatsch. Unfortunately, fixing this is not as simple as just fixing Haddock, because both Hackage and Stackage manually reimplemented the module listing logic, so that logic needs to be adjusted as well for module reexports. This seemed to involve some sort of massive refactor which is why I ended up putting it off (the other yak I need to shave being making it easy to deploy changes to Hackage...)

@Profpatsch

Is there any part of the Haskell infrastructure that is currently not maintained by you? oO

@ezyang
Contributor
ezyang commented Dec 24, 2016

Nah, I don't have commit or deploy bits for Hackage ;)

@minad
minad commented Dec 24, 2016

@ezyang I would also like to have this feature, since this one also leads to contradicting recommendations (hlint etc). I didn't really understand your comment about the module listing logic. Are there larger architectural changes planned or is it possible to fix that in a quick way that just works?

@ezyang
Contributor
ezyang commented Dec 24, 2016

I have already written a patch to change the Haddock generated index page to handle reexported modules, the patch is here: #547 But as I mentioned above, this only affects the index page that Haddock creates, which is NOT the one that Hackage/Stackage uses.

I've never worked with the hackage-server codebase before, so I didn't get very far trying to adjust hackage-server (once again, mostly because I knew, even if I patched hackage-server, I didn't know how I was going to go about deploying my changes. At this point I decided to terminate the yakstack.)

Here is what I did find: there is a reimplementation of the index logic in the following modules:

I didn't spend very much time figuring out how to make this work.

There is another possible approach to solving this problem, which is to go about doing the Haddock patch differently: instead of just linking to the reexport module documentation, you just create another copy of the documentation from the current package. But this is a bit annoying because Haddock's interface files don't seem to save enough information to actually do this (it's the difference between InstalledInterface and Interface in https://github.com/haskell/haddock/blob/master/haddock-api/src/Haddock/Types.hs). I tried making Interface serializable but it had some references to GHC types so I gave up. Maybe there's a different way we could go about doing it.

@minad
minad commented Dec 24, 2016

Thx for the detailed explanation!

@ezyang
Contributor
ezyang commented Jan 19, 2017

My thinking on this matter has changed; I think that it is probably best if we teach Haddock how to reproduce documentation for reexported modules, rather than try to do something funny with redirecting links to the sources of them. So maybe there is some way to reconstruct the GHC types next time we're running (maybe by reading in their interfaces) and going from there.

@Profpatsch

next time we're running

While we’re at it maybe implement hashing (incremental rebuild) as well? The interface files don’t have the comments I assume? But hashing over the input hs files should be a good first approximation (up to edge cases) probably?

@ezyang
Contributor
ezyang commented Jan 22, 2017

@Profpatsch File another bug for that ;)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment