Investigation into a Haddock hyperlink bug (GHC 9.8 to 9.14)

I recently decided to get to the bottom of a bug that causes broken hyperlinks in Haddock documentation. I’m sharing what I found in case it helps others, and to hopefully shed some light on the problem!

What is the bug?

The bug appears whenever a Haddock documentation comment refers to an identifier through a qualified import alias. For example:

import qualified Data.Map.Strict as Map

-- | See 'Map.lookup'.

Behaviour

  • :white_check_mark: With the haddock bundled with GHC 8.0 to 9.6, the generated documentation correctly links to lookup in Data.Map.Strict, as you might expect.

  • :cross_mark: With the haddock bundled with GHC 9.8 to 9.14, the generated documentation links to Map.html#v:lookup, a page that doesn’t exist. :crying_cat:

Since Hackage (currently) builds documentation with GHC 9.8.4 (which uses Haddock 2.30.0), this means Hackage is also affected.

Workarounds

:white_check_mark: References that use the full module name still link correctly with every version of GHC and haddock I tested:

-- | See 'Data.Map.Strict.lookup'.

:white_check_mark: So do references to identifiers that are imported unqualified:

-- | See 'lookup'.

Though this requires bringing the name into scope, which can clash with other names (lookup clashes with Prelude.lookup, for example).

How long has this been broken?

Probably since GHC 9.8.1, which was released in October 2023, so for about three years. (Of the 9.8 releases, I tested only the latest, 9.8.4.)

Investigation

To investigate this more thoroughly, I put together a small package called haddock-hyperlink-test with a test module Demo.hs whose documentation refers to four identifiers, each imported in a different way:

-- | Each row below shows an import, a reference to the entity exported by the
--   imported module, and the link that Haddock generates for that reference.
--
-- +--------------------------------------+------------------------+--------------------+
-- | Import                               | Reference              | Link               |
-- +======================================+========================+====================+
-- | @import Demo.ModuleA (foo)@          | @\'foo\'@              | 'foo'              |
-- +--------------------------------------+------------------------+--------------------+
-- | @import qualified Demo.ModuleB@      | @\'Demo.ModuleB.bar\'@ | 'Demo.ModuleB.bar' |
-- +--------------------------------------+------------------------+--------------------+
-- | @import qualified Demo.ModuleC as C@ | @\'C.baz\'@            | 'C.baz'            |
-- +--------------------------------------+------------------------+--------------------+
-- | @(none)@                             | @\'Demo.ModuleD.qux\'@ | 'Demo.ModuleD.qux' |
-- +--------------------------------------+------------------------+--------------------+
--
module Demo (examples) where

import Demo.ModuleA (foo)
import qualified Demo.ModuleB
import qualified Demo.ModuleC as C

A GitHub Actions workflow builds the documentation for this package with every major version of GHC from 8.0 to 9.14, and checks where each link leads. (The same workflow also builds haddock from source at eight consecutive commits around the point where the behaviour changes.)

Results

I’ve published the results here: Haddock links by GHC version and Haddock commit

The behavioural change appears to happen at this Haddock commit: 8b6ec7dc. The four commits up to that point link correctly, and the four from it onwards don’t.

What’s next?

I’ve already shared these results on ticket #25136, which appears to report the same problem.

Since this might affect quite a few packages on Hackage, I thought it was worth sharing here too, just in case it helps someone else who is scratching their head at broken links (like I was).

Thanks for reading!

14 Likes