When Haddock renders a type in the generated documentation, it hyperlinks all the type constructors and class names in that type to their respective definitions. But for a given type constructor or class there may be several modules re-exporting it, and therefore several modules whose documentation contains the definition of that type or class (possibly including the current module!) so which one do we link to?
Let's look at an example. Suppose we have three modules
A
, B
and
C
defined as follows:
module A (T) where data T a = C a module B (f) where import A f :: T Int -> Int f (C i) = i module C (T, f) where import A import B
Module A
exports a datatype
T
. Module B
imports
A
and exports a function f
whose type refers to T
. Also, both
T
and f
are re-exported from
module C.
Haddock takes the view that each entity has a home module; that is, the module that the library designer would most like to direct the user to, to find the documentation for that entity. So, Haddock makes all links to an entity point to the home module. The one exception is when the entity is also exported by the current module: Haddock makes a local link if it can.
How is the home module for an entity determined? Haddock uses the following rules:
If modules A and B both export the entity, and module A imports (directly or indirectly) module B, then B is preferred.
A module with the hide
attribute is never
chosen as the home.
A module with the not-home
attribute is only
chosen if there are no other modules to choose.
If multiple modules fit the criteria, then one is chosen at random. If no modules fit the criteria (because the candidates are all hidden), then Haddock will issue a warning for each reference to an entity without a home.
In the example above, module A
is chosen as the
home for T
because it does not import any other
module that exports T
. The link from
f
's
type in module B
will therefore point to
A.T
. However, C
also exports
T
and f
, and the link from
f
's type in C
will therefore
point locally to C.T
.