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:
Similarly, ghcjs-dom-jsffi reexports and renames said modules, those are then used (and reexported) by ghcjs-dom again:
Also, the documentation is broken in that case (ghcjs-dom references the renamed modules internally).
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...)
Is there any part of the Haskell infrastructure that is currently not maintained by you? oO
Nah, I don't have commit or deploy bits for Hackage ;)
@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?
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.
Thx for the detailed explanation!
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.
next time we're running
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?
@Profpatsch File another bug for that ;)