[Git][ghc/ghc][master] haddock: Document instances from other packages

8 Jul 2025


      Marge Bot pushed to branch master at Glasgow Haskell Compiler / GHC


Commits:
a26243fd by Ryan Hendrickson at 2025-07-07T20:43:07-04:00
haddock: Document instances from other packages

When attaching instances to `Interface`s, it isn't enough just to look
for instances in the list of `Interface`s being processed. We also need
to look in the modules on which they depend, including those outside of
this package.

Fixes #25147.
Fixes #26079.

- - - - -


6 changed files:

- utils/haddock/CHANGES.md
- utils/haddock/haddock-api/src/Haddock/Interface/AttachInstances.hs
- utils/haddock/haddock-api/src/Haddock/Interface/Create.hs
- utils/haddock/haddock-api/src/Haddock/Types.hs
- utils/haddock/haddock-test/src/Test/Haddock/Config.hs
- utils/haddock/html-test/ref/Bug1004.html


Changes:

=====================================
utils/haddock/CHANGES.md
=====================================
@@ -1,6 +1,8 @@
 ## Changes in 2.32.0
  * Add highlighting for inline-code-blocks (sections enclosed in @'s)
 
+ * Fix missing documentation for orphan instances from other packages.
+
  * Add incremental mode to support rendering documentation one module at a time.
 
  * The flag `--no-compilation` has been added. This flag causes Haddock to avoid


=====================================
utils/haddock/haddock-api/src/Haddock/Interface/AttachInstances.hs
=====================================
@@ -88,7 +88,10 @@ attachInstances expInfo ifaces instIfaceMap isOneShot = do
           , fromOrig == Just True || not (null reExp)
           ]
       mods_to_load = moduleSetElts mods
-      mods_visible = mkModuleSet $ map ifaceMod ifaces
+      -- We need to ensure orphans in modules outside of this package are included.
+      -- See https://gitlab.haskell.org/ghc/ghc/-/issues/25147
+      -- and https://gitlab.haskell.org/ghc/ghc/-/issues/26079
+      mods_visible = mkModuleSet $ concatMap (liftA2 (:) ifaceMod ifaceOrphanDeps) ifaces
 
   (_msgs, mb_index) <- do
     hsc_env <- getSession


=====================================
utils/haddock/haddock-api/src/Haddock/Interface/Create.hs
=====================================
@@ -59,6 +59,7 @@ import GHC.Types.Name.Set
 import GHC.Types.SafeHaskell
 import qualified GHC.Types.SrcLoc as SrcLoc
 import qualified GHC.Types.Unique.Map as UniqMap
+import GHC.Unit.Module.Deps (dep_orphs)
 import GHC.Unit.Module.ModIface
 import GHC.Unit.State (PackageName (..), UnitState)
 import GHC.Utils.Outputable (SDocContext)
@@ -270,6 +271,7 @@ createInterface1' flags unit_state dflags hie_file mod_iface ifaces inst_ifaces
       , ifaceVisibleExports = visible_names
       , ifaceFixMap = fixities
       , ifaceInstances = instances
+      , ifaceOrphanDeps = dep_orphs $ mi_deps mod_iface
       , ifaceOrphanInstances = [] -- Filled in attachInstances
       , ifaceRnOrphanInstances = [] -- Filled in renameInterfaceRn
       , ifaceHaddockCoverage = coverage


=====================================
utils/haddock/haddock-api/src/Haddock/Types.hs
=====================================
@@ -134,6 +134,9 @@ data Interface = Interface
   -- Names from modules that are entirely re-exported don't count as visible.
   , ifaceInstances :: [ClsInst]
   -- ^ Instances exported by the module.
+  , ifaceOrphanDeps :: [Module]
+  -- ^ The list of modules to check for orphan instances if this module is
+  -- imported.
   , ifaceOrphanInstances :: [DocInstance GhcRn]
   -- ^ Orphan instances
   , ifaceRnOrphanInstances :: [DocInstance DocNameI]


=====================================
utils/haddock/haddock-test/src/Test/Haddock/Config.hs
=====================================
@@ -262,6 +262,7 @@ baseDependencies ghcPath = do
       pkgs =
         [ "array"
         , "base"
+        , "deepseq"
         , "ghc-prim"
         , "process"
         , "template-haskell"


=====================================
utils/haddock/html-test/ref/Bug1004.html
=====================================
@@ -833,7 +833,61 @@
 		><tr
 		><td class="src clearfix"
 		  ><span class="inst-left"
-		    ><span class="instance details-toggle-control details-toggle" data-details-id="i:id:Product:Alternative:8"
+		    ><span class="instance details-toggle-control details-toggle" data-details-id="i:id:Product:NFData1:8"
+		      ></span
+		      > <span class="breakable"
+		      >(<span class="unbreakable"
+			><a href="#" title="Control.DeepSeq"
+			  >NFData1</a
+			  > f</span
+			>, <span class="unbreakable"
+			><a href="#" title="Control.DeepSeq"
+			  >NFData1</a
+			  > g</span
+			>)</span
+		      > => <a href="#" title="Control.DeepSeq"
+		      >NFData1</a
+		      > (<a href="#" title="Bug1004"
+		      >Product</a
+		      > f g)</span
+		    > <a href="#" class="selflink"
+		    >#</a
+		    ></td
+		  ><td class="doc"
+		  ><p
+		    ><em
+		      >Since: deepseq-1.4.3.0</em
+		      ></p
+		    ></td
+		  ></tr
+		><tr
+		><td colspan="2"
+		  ><details id="i:id:Product:NFData1:8"
+		    ><summary class="hide-when-js-enabled"
+		      >Instance details</summary
+		      ><p
+		      >Defined in <a href="#"
+			>Control.DeepSeq</a
+			></p
+		      > <div class="subs methods"
+		      ><p class="caption"
+			>Methods</p
+			><p class="src"
+			><a href="#"
+			  >liftRnf</a
+			  > :: (a -> ()) -> <a href="#" title="Bug1004"
+			  >Product</a
+			  > f g a -> () <a href="#" class="selflink"
+			  >#</a
+			  ></p
+			></div
+		      ></details
+		    ></td
+		  ></tr
+		><tr
+		><td class="src clearfix"
+		  ><span class="inst-left"
+		    ><span class="instance details-toggle-control details-toggle" data-details-id="i:id:Product:Alternative:9"
 		      ></span
 		      > <span class="breakable"
 		      >(<span class="unbreakable"
@@ -862,7 +916,7 @@
 		  ></tr
 		><tr
 		><td colspan="2"
-		  ><details id="i:id:Product:Alternative:8"
+		  ><details id="i:id:Product:Alternative:9"
 		    ><summary class="hide-when-js-enabled"
 		      >Instance details</summary
 		      ><p
@@ -919,7 +973,7 @@
 		><tr
 		><td class="src clearfix"
 		  ><span class="inst-left"
-		    ><span class="instance details-toggle-control details-toggle" data-details-id="i:id:Product:Applicative:9"
+		    ><span class="instance details-toggle-control details-toggle" data-details-id="i:id:Product:Applicative:10"
 		      ></span
 		      > <span class="breakable"
 		      >(<span class="unbreakable"
@@ -948,7 +1002,7 @@
 		  ></tr
 		><tr
 		><td colspan="2"
-		  ><details id="i:id:Product:Applicative:9"
+		  ><details id="i:id:Product:Applicative:10"
 		    ><summary class="hide-when-js-enabled"
 		      >Instance details</summary
 		      ><p
@@ -1021,7 +1075,7 @@
 		><tr
 		><td class="src clearfix"
 		  ><span class="inst-left"
-		    ><span class="instance details-toggle-control details-toggle" data-details-id="i:id:Product:Functor:10"
+		    ><span class="instance details-toggle-control details-toggle" data-details-id="i:id:Product:Functor:11"
 		      ></span
 		      > <span class="breakable"
 		      >(<span class="unbreakable"
@@ -1050,7 +1104,7 @@
 		  ></tr
 		><tr
 		><td colspan="2"
-		  ><details id="i:id:Product:Functor:10"
+		  ><details id="i:id:Product:Functor:11"
 		    ><summary class="hide-when-js-enabled"
 		      >Instance details</summary
 		      ><p
@@ -1087,7 +1141,7 @@
 		><tr
 		><td class="src clearfix"
 		  ><span class="inst-left"
-		    ><span class="instance details-toggle-control details-toggle" data-details-id="i:id:Product:Monad:11"
+		    ><span class="instance details-toggle-control details-toggle" data-details-id="i:id:Product:Monad:12"
 		      ></span
 		      > <span class="breakable"
 		      >(<span class="unbreakable"
@@ -1116,7 +1170,7 @@
 		  ></tr
 		><tr
 		><td colspan="2"
-		  ><details id="i:id:Product:Monad:11"
+		  ><details id="i:id:Product:Monad:12"
 		    ><summary class="hide-when-js-enabled"
 		      >Instance details</summary
 		      ><p
@@ -1165,7 +1219,7 @@
 		><tr
 		><td class="src clearfix"
 		  ><span class="inst-left"
-		    ><span class="instance details-toggle-control details-toggle" data-details-id="i:id:Product:MonadPlus:12"
+		    ><span class="instance details-toggle-control details-toggle" data-details-id="i:id:Product:MonadPlus:13"
 		      ></span
 		      > <span class="breakable"
 		      >(<span class="unbreakable"
@@ -1194,7 +1248,7 @@
 		  ></tr
 		><tr
 		><td colspan="2"
-		  ><details id="i:id:Product:MonadPlus:12"
+		  ><details id="i:id:Product:MonadPlus:13"
 		    ><summary class="hide-when-js-enabled"
 		      >Instance details</summary
 		      ><p
@@ -1231,7 +1285,7 @@
 		><tr
 		><td class="src clearfix"
 		  ><span class="inst-left"
-		    ><span class="instance details-toggle-control details-toggle" data-details-id="i:id:Product:MonadFix:13"
+		    ><span class="instance details-toggle-control details-toggle" data-details-id="i:id:Product:MonadFix:14"
 		      ></span
 		      > <span class="breakable"
 		      >(<span class="unbreakable"
@@ -1260,7 +1314,7 @@
 		  ></tr
 		><tr
 		><td colspan="2"
-		  ><details id="i:id:Product:MonadFix:13"
+		  ><details id="i:id:Product:MonadFix:14"
 		    ><summary class="hide-when-js-enabled"
 		      >Instance details</summary
 		      ><p
@@ -1287,7 +1341,7 @@
 		><tr
 		><td class="src clearfix"
 		  ><span class="inst-left"
-		    ><span class="instance details-toggle-control details-toggle" data-details-id="i:id:Product:MonadZip:14"
+		    ><span class="instance details-toggle-control details-toggle" data-details-id="i:id:Product:MonadZip:15"
 		      ></span
 		      > <span class="breakable"
 		      >(<span class="unbreakable"
@@ -1316,7 +1370,7 @@
 		  ></tr
 		><tr
 		><td colspan="2"
-		  ><details id="i:id:Product:MonadZip:14"
+		  ><details id="i:id:Product:MonadZip:15"
 		    ><summary class="hide-when-js-enabled"
 		      >Instance details</summary
 		      ><p
@@ -1369,7 +1423,7 @@
 		><tr
 		><td class="src clearfix"
 		  ><span class="inst-left"
-		    ><span class="instance details-toggle-control details-toggle" data-details-id="i:id:Product:Foldable:15"
+		    ><span class="instance details-toggle-control details-toggle" data-details-id="i:id:Product:Foldable:16"
 		      ></span
 		      > <span class="breakable"
 		      >(<span class="unbreakable"
@@ -1398,7 +1452,7 @@
 		  ></tr
 		><tr
 		><td colspan="2"
-		  ><details id="i:id:Product:Foldable:15"
+		  ><details id="i:id:Product:Foldable:16"
 		    ><summary class="hide-when-js-enabled"
 		      >Instance details</summary
 		      ><p
@@ -1573,7 +1627,7 @@
 		><tr
 		><td class="src clearfix"
 		  ><span class="inst-left"
-		    ><span class="instance details-toggle-control details-toggle" data-details-id="i:id:Product:Traversable:16"
+		    ><span class="instance details-toggle-control details-toggle" data-details-id="i:id:Product:Traversable:17"
 		      ></span
 		      > <span class="breakable"
 		      >(<span class="unbreakable"
@@ -1602,7 +1656,7 @@
 		  ></tr
 		><tr
 		><td colspan="2"
-		  ><details id="i:id:Product:Traversable:16"
+		  ><details id="i:id:Product:Traversable:17"
 		    ><summary class="hide-when-js-enabled"
 		      >Instance details</summary
 		      ><p
@@ -1667,7 +1721,65 @@
 		><tr
 		><td class="src clearfix"
 		  ><span class="inst-left"
-		    ><span class="instance details-toggle-control details-toggle" data-details-id="i:id:Product:Monoid:17"
+		    ><span class="instance details-toggle-control details-toggle" data-details-id="i:id:Product:NFData:18"
+		      ></span
+		      > <span class="breakable"
+		      >(<span class="unbreakable"
+			><a href="#" title="Control.DeepSeq"
+			  >NFData</a
+			  > (f a)</span
+			>, <span class="unbreakable"
+			><a href="#" title="Control.DeepSeq"
+			  >NFData</a
+			  > (g a)</span
+			>)</span
+		      > => <a href="#" title="Control.DeepSeq"
+		      >NFData</a
+		      > (<a href="#" title="Bug1004"
+		      >Product</a
+		      > f g a)</span
+		    > <a href="#" class="selflink"
+		    >#</a
+		    ></td
+		  ><td class="doc"
+		  ><p
+		    >Note: in <code class="inline-code"
+		      >deepseq-1.5.0.0</code
+		      > this instance's superclasses were changed.</p
+		    ><p
+		    ><em
+		      >Since: deepseq-1.4.3.0</em
+		      ></p
+		    ></td
+		  ></tr
+		><tr
+		><td colspan="2"
+		  ><details id="i:id:Product:NFData:18"
+		    ><summary class="hide-when-js-enabled"
+		      >Instance details</summary
+		      ><p
+		      >Defined in <a href="#"
+			>Control.DeepSeq</a
+			></p
+		      > <div class="subs methods"
+		      ><p class="caption"
+			>Methods</p
+			><p class="src"
+			><a href="#"
+			  >rnf</a
+			  > :: <a href="#" title="Bug1004"
+			  >Product</a
+			  > f g a -> () <a href="#" class="selflink"
+			  >#</a
+			  ></p
+			></div
+		      ></details
+		    ></td
+		  ></tr
+		><tr
+		><td class="src clearfix"
+		  ><span class="inst-left"
+		    ><span class="instance details-toggle-control details-toggle" data-details-id="i:id:Product:Monoid:19"
 		      ></span
 		      > <span class="breakable"
 		      >(<span class="unbreakable"
@@ -1696,7 +1808,7 @@
 		  ></tr
 		><tr
 		><td colspan="2"
-		  ><details id="i:id:Product:Monoid:17"
+		  ><details id="i:id:Product:Monoid:19"
 		    ><summary class="hide-when-js-enabled"
 		      >Instance details</summary
 		      ><p
@@ -1743,7 +1855,7 @@
 		><tr
 		><td class="src clearfix"
 		  ><span class="inst-left"
-		    ><span class="instance details-toggle-control details-toggle" data-details-id="i:id:Product:Semigroup:18"
+		    ><span class="instance details-toggle-control details-toggle" data-details-id="i:id:Product:Semigroup:20"
 		      ></span
 		      > <span class="breakable"
 		      >(<span class="unbreakable"
@@ -1772,7 +1884,7 @@
 		  ></tr
 		><tr
 		><td colspan="2"
-		  ><details id="i:id:Product:Semigroup:18"
+		  ><details id="i:id:Product:Semigroup:20"
 		    ><summary class="hide-when-js-enabled"
 		      >Instance details</summary
 		      ><p
@@ -1825,7 +1937,7 @@
 		><tr
 		><td class="src clearfix"
 		  ><span class="inst-left"
-		    ><span class="instance details-toggle-control details-toggle" data-details-id="i:id:Product:Eq:19"
+		    ><span class="instance details-toggle-control details-toggle" data-details-id="i:id:Product:Eq:21"
 		      ></span
 		      > <span class="breakable"
 		      >(<span class="unbreakable"
@@ -1854,7 +1966,7 @@
 		  ></tr
 		><tr
 		><td colspan="2"
-		  ><details id="i:id:Product:Eq:19"
+		  ><details id="i:id:Product:Eq:21"
 		    ><summary class="hide-when-js-enabled"
 		      >Instance details</summary
 		      ><p
@@ -1895,7 +2007,7 @@
 		><tr
 		><td class="src clearfix"
 		  ><span class="inst-left"
-		    ><span class="instance details-toggle-control details-toggle" data-details-id="i:id:Product:Ord:20"
+		    ><span class="instance details-toggle-control details-toggle" data-details-id="i:id:Product:Ord:22"
 		      ></span
 		      > <span class="breakable"
 		      >(<span class="unbreakable"
@@ -1924,7 +2036,7 @@
 		  ></tr
 		><tr
 		><td colspan="2"
-		  ><details id="i:id:Product:Ord:20"
+		  ><details id="i:id:Product:Ord:22"
 		    ><summary class="hide-when-js-enabled"
 		      >Instance details</summary
 		      ><p
@@ -2025,7 +2137,7 @@
 		><tr
 		><td class="src clearfix"
 		  ><span class="inst-left"
-		    ><span class="instance details-toggle-control details-toggle" data-details-id="i:id:Product:Data:21"
+		    ><span class="instance details-toggle-control details-toggle" data-details-id="i:id:Product:Data:23"
 		      ></span
 		      > <span class="breakable"
 		      >(<span class="unbreakable"
@@ -2070,7 +2182,7 @@
 		  ></tr
 		><tr
 		><td colspan="2"
-		  ><details id="i:id:Product:Data:21"
+		  ><details id="i:id:Product:Data:23"
 		    ><summary class="hide-when-js-enabled"
 		      >Instance details</summary
 		      ><p
@@ -2293,7 +2405,7 @@
 		><tr
 		><td class="src clearfix"
 		  ><span class="inst-left"
-		    ><span class="instance details-toggle-control details-toggle" data-details-id="i:id:Product:Generic:22"
+		    ><span class="instance details-toggle-control details-toggle" data-details-id="i:id:Product:Generic:24"
 		      ></span
 		      > <a href="#" title="GHC.Generics"
 		      >Generic</a
@@ -2308,7 +2420,7 @@
 		  ></tr
 		><tr
 		><td colspan="2"
-		  ><details id="i:id:Product:Generic:22"
+		  ><details id="i:id:Product:Generic:24"
 		    ><summary class="hide-when-js-enabled"
 		      >Instance details</summary
 		      ><p
@@ -2447,7 +2559,7 @@
 		><tr
 		><td class="src clearfix"
 		  ><span class="inst-left"
-		    ><span class="instance details-toggle-control details-toggle" data-details-id="i:id:Product:Read:23"
+		    ><span class="instance details-toggle-control details-toggle" data-details-id="i:id:Product:Read:25"
 		      ></span
 		      > <span class="breakable"
 		      >(<span class="unbreakable"
@@ -2476,7 +2588,7 @@
 		  ></tr
 		><tr
 		><td colspan="2"
-		  ><details id="i:id:Product:Read:23"
+		  ><details id="i:id:Product:Read:25"
 		    ><summary class="hide-when-js-enabled"
 		      >Instance details</summary
 		      ><p
@@ -2535,7 +2647,7 @@
 		><tr
 		><td class="src clearfix"
 		  ><span class="inst-left"
-		    ><span class="instance details-toggle-control details-toggle" data-details-id="i:id:Product:Show:24"
+		    ><span class="instance details-toggle-control details-toggle" data-details-id="i:id:Product:Show:26"
 		      ></span
 		      > <span class="breakable"
 		      >(<span class="unbreakable"
@@ -2564,7 +2676,7 @@
 		  ></tr
 		><tr
 		><td colspan="2"
-		  ><details id="i:id:Product:Show:24"
+		  ><details id="i:id:Product:Show:26"
 		    ><summary class="hide-when-js-enabled"
 		      >Instance details</summary
 		      ><p
@@ -2613,7 +2725,7 @@
 		><tr
 		><td class="src clearfix"
 		  ><span class="inst-left"
-		    ><span class="instance details-toggle-control details-toggle" data-details-id="i:id:Product:Rep1:25"
+		    ><span class="instance details-toggle-control details-toggle" data-details-id="i:id:Product:Rep1:27"
 		      ></span
 		      > <span class="keyword"
 		      >type</span
@@ -2636,7 +2748,7 @@
 		  ></tr
 		><tr
 		><td colspan="2"
-		  ><details id="i:id:Product:Rep1:25"
+		  ><details id="i:id:Product:Rep1:27"
 		    ><summary class="hide-when-js-enabled"
 		      >Instance details</summary
 		      ><p
@@ -2711,7 +2823,7 @@
 		><tr
 		><td class="src clearfix"
 		  ><span class="inst-left"
-		    ><span class="instance details-toggle-control details-toggle" data-details-id="i:id:Product:Rep:26"
+		    ><span class="instance details-toggle-control details-toggle" data-details-id="i:id:Product:Rep:28"
 		      ></span
 		      > <span class="keyword"
 		      >type</span
@@ -2732,7 +2844,7 @@
 		  ></tr
 		><tr
 		><td colspan="2"
-		  ><details id="i:id:Product:Rep:26"
+		  ><details id="i:id:Product:Rep:28"
 		    ><summary class="hide-when-js-enabled"
 		      >Instance details</summary
 		      ><p



View it on GitLab: https://gitlab.haskell.org/ghc/ghc/-/commit/a26243fde4680271712a3d774e17f6cd...

-- 
View it on GitLab: https://gitlab.haskell.org/ghc/ghc/-/commit/a26243fde4680271712a3d774e17f6cd...
You're receiving this email because of your account on gitlab.haskell.org.

    

Marge Bot (＠marge-bot)

tags

participants (1)