3.6. Hyperlinking and re-exported entities
Prev | Chapter 3. Documentation and Markup | Next

## 3.6. Hyperlinking and re-exported entities

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` atribute 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`.

Prev | Up | Next
3.5. Named chunks of documentation | Home | 3.7. Module Attributes