haskell / haddock

Haskell Documentation Tool
www.haskell.org/haddock/
BSD 2-Clause "Simplified" License
361 stars 242 forks source link

Confusing rendering of 'ToJSON' reference in Data.Aeson.TH module docs (Haddock 2.20.0+ ?) #1606

Closed PiDelport closed 1 month ago

PiDelport commented 12 months ago

The Aeson library's Data.Aeson.TH module documentation references the 'ToJSON' type class in several places.

This reference renders correctly as a link to the type class up to version 1.4.1.0 of the library, but for later versions of the library, it renders inconsistently as one of the following, with no obvious pattern:

  1. Sometimes (confusingly!) as the unlinked identifier JSONFun (for example: 1.4.2.0, 2.2.0.0)
  2. Sometimes as the unlinked identifier ToJSON (for example: 1.5.5.0, 2.1.0.0)

Note that the Data.Aeson.TH module contains the following internal definition, which is presumably part of the problem:

data JSONFun = ToJSON | ToEncoding | ParseJSON

Based on the Haddock versions used for the Hackage documentation, it looks like the rendering change happened around Haddock 2.20.0, but note that both Aeson 1.4.1.0 (correct) and 1.4.2.0 (JSONFun) were rendered by Haddock 2.20.0, so that may not explain everything.

Kleidukos commented 1 month ago

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. :)