Haddock User Guide
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`: the hyperlink in `f`'s signature will point to the definition of `T` in the documentation for module `A`.

Now, module `C` exports both `T` and `f`. We have a choice about where to point the hyperlink to `T` in `f`'s type: either the definition exported by module `C` or the definition exported by module `A`. Haddock takes the view that in this case pointing to the definition in `C` is better, because the programmer might not wish to expose `A` to the programmer at all: `A` might be a module internal to the implementation of the library in which `C` is the external interface, so linking to definitions in the current module is preferrable over an imported module.

The general rule is this: when attempting to link an instance of a type constructor or class to its definition, the link is made to

- the current module, if the current module exports the relevant definition, or

- the module that the entity was imported from, otherwise. If the entity was imported via multiple routes, then Haddock picks the module listed earliest in the imports of the current module.

Prev | Home | Next
Named chunks of documentation | Up | Module Attributes