Haddock renders ambiguous type/value names strangely

[Ryan Scott]

(Originally observed in ekmett/lens#1042.)

Here is a stripped-down version of Haddocks that you'd find in a typical lens module:

-- Bug.hs
module Bug where

data ReifiedLens = Lens

type Lens = ()

-- | A 'Lens'.
f :: Lens
f = ()

Note that the 'Lens' reference in f's Haddocks is ambiguous, as there is both a type and a data constructor named Lens. My reading of this section of the Haddock readthedocs is that when such ambiguities arise, Haddock will default to the type name:

Since values and types live in different namespaces in Haskell, it is possible for a reference such as 'X' to be ambiguous. In such a case, Haddock defaults to pointing to the type.

This is not what I observe in practice, however. If you render the Haddocks for this module by running the following command:

$ haddock Bug.hs -o bug --html
Warning: 'Lens' is ambiguous. It is defined
    * at Bug.hs:4:20
    * at Bug.hs:6:1
    You may be able to disambiguate the identifier by qualifying it or
    by specifying the type/value namespace explicitly.
    Defaulting to the one defined at Bug.hs:4:1
  25% (  1 /  4) in 'Bug'
  Missing documentation for:
    Module header
    ReifiedLens (Bug.hs:4)
    Lens (Bug.hs:6)

You will end up with the following HTML page:

I believe there are two bugs here:

1. The rendered Haddocks say "RenderedLens", which is completely different from the original "'Lens'". I'm not sure why this happens.
2. Moreover, RenderedLens refers to the value-level version of Lens, not the type-level Lens. If I understood the readthedocs correctly, it should be the other way around.

[Naïm Favier]

Note that I can't reproduce this bug on the ghc-9.6 branch of this repo, so presumably #1597 helped (cc @FinleyMcIlwaine).

Regarding the buggy code though, this comment looks suspicious to me...

[Naïm Favier]

After some debugging,

choices = [Lens, Lens]
gres = [Lens parent:ReifiedLens defined at Bug.hs:4:20,
 Lens defined at Bug.hs:6:1]
gresToAvailInfo gres = [Lens{Lens}, ReifiedLens{Lens}]
noChildren = [Lens, ReifiedLens]

So the problem seems to be that gresToAvailInfo turns the data constructor Lens into its parent type constructor ReifiedLens and we lose the information that it came from a data constructor.

[Hécate]

Hi, thank you for this ticket, but Haddock now lives full-time in the GHC repository!
Read more at https://discourse.haskell.org/t/haddock-now-lives-in-the-ghc-repository/9576.

Let me know if you feel it is still needed, and I'll migrate it. :)