Avoid Haddock-links to the Prelude

[waern]

If you're generating documenatation that links to the base package, you will see that some links to standard types go to the Prelude and some to the hierarchical libararies. For example, Int goes to Prelude.Int, while Either goes to Data.Either.Either.

This happens because the Prelude imports some types from the hierarchical libraries, while some are imported directly from internal GHC modules (e.g. GHC.Base). In the first case, the hierarchical module is choosen as the best place to link to since it's closer than the Prelude in the topological sort to the original module. In the latter case, the hierarchical module and the Prelude are of equal number of imports away from the original module, so none is considered a better place to link to. In this case one of the modules is arbitrarily chosen and it happens to be the Prelude.

I think it would be nice if the links would always go to the hierarchical libraries. Maybe the best way to achieve that would be to add {-# OPTIONS_HADDOCK NotHome #-} to the Prelude. This flag is not yet documented (I should get around to that). It tells Haddock to prefer linking to another module if one is available.

[ross]

Isn't the reason Prelude.Int is chosen that GHC.Base is hidden, because it isn't part of the public interface of the package?

[waern]

Replying to ross:

Isn't the reason Prelude.Int is chosen that GHC.Base is hidden, because it isn't part of the public interface of the package?

GHC.Base is not chosen because it is hidden, but that leaves the choice to either Prelude.Int or Data.Int. Haddock prefers the module that is closest to the original module in the dependency tree. Since both Prelude.Int and Data.Int directly imports GHC.Base, they are at the same level of the dependency tree and thus Haddock has to make an arbitrary choice. If Prelude had imported Data.Int and not GHC.Base (just for illustration; such a restructuring may be hard to do since Prelude imports many more things via GHC.Base), the link would go to Data.Int.