base: Add references to Notes for certain special imports

Summary:
Modules like GHC.Integer, GHC.Natural etc. are special and sometimes
have to be imported just to resolve build ordering issues. It's useful
to refer to the appropriate Notes at such import sites.

Test Plan: Read it.

Reviewers: RyanGlScott, bgamari, hvr, simonpj

Reviewed By: RyanGlScott, simonpj

Subscribers: simonpj, rwbarton, carter

GHC Trac Issues: #15526

Differential Revision: https://phabricator.haskell.org/D5092

6 files changed, 11 insertions, 9 deletions

diff --git a/libraries/base/Data/Semigroup/Internal.hs-boot b/libraries/base/Data/Semigroup/Internal.hs-boot
index 80750242fb..36249294e7 100644
--- a/libraries/base/Data/Semigroup/Internal.hs-boot
+++ b/libraries/base/Data/Semigroup/Internal.hs-boot
@@ -4,7 +4,7 @@ module Data.Semigroup.Internal where
 
 import {-# SOURCE #-} GHC.Real (Integral)
 import {-# SOURCE #-} GHC.Base (Semigroup,Monoid,Maybe)
-import GHC.Integer ()   -- Note [Depend on GHC.Integer]
+import GHC.Integer () -- See Note [Depend on GHC.Integer] in GHC.Base
 
 stimesIdempotentMonoid :: (Integral b, Monoid a) => b -> a -> a
 
diff --git a/libraries/base/GHC/Err.hs b/libraries/base/GHC/Err.hs
index 1f1ad903ae..095ccd8dd7 100644
--- a/libraries/base/GHC/Err.hs
+++ b/libraries/base/GHC/Err.hs
@@ -29,7 +29,9 @@ import GHC.Stack.Types
 import GHC.Prim
 import GHC.Integer ()   -- Make sure Integer and Natural are compiled first
 import GHC.Natural ()   -- because GHC depends on it in a wired-in way
-                        -- so the build system doesn't see the dependency
+                        -- so the build system doesn't see the dependency.
+                        -- See Note [Depend on GHC.Integer] and
+                        -- Note [Depend on GHC.Natural] in GHC.Base.
 import {-# SOURCE #-} GHC.Exception
   ( errorCallWithCallStackException
   , errorCallException )
diff --git a/libraries/base/GHC/IO.hs-boot b/libraries/base/GHC/IO.hs-boot
index f1e50fe111..aa2e5ccd2d 100644
--- a/libraries/base/GHC/IO.hs-boot
+++ b/libraries/base/GHC/IO.hs-boot
@@ -4,7 +4,7 @@
 module GHC.IO where
 
 import GHC.Types
-import GHC.Integer () -- see Note [Depend upon GHC.Integer] in libraries/base/GHC/Base.hs
+import GHC.Integer () -- See Note [Depend on GHC.Integer] in GHC.Base
 
 failIO :: [Char] -> IO a
 mplusIO :: IO a -> IO a -> IO a
diff --git a/libraries/base/GHC/Maybe.hs b/libraries/base/GHC/Maybe.hs
index 373fd48714..2bdfac54a2 100644
--- a/libraries/base/GHC/Maybe.hs
+++ b/libraries/base/GHC/Maybe.hs
@@ -6,7 +6,7 @@ module GHC.Maybe
    )
 where
 
-import GHC.Integer () -- for build order
+import GHC.Integer () -- See Note [Depend on GHC.Integer] in GHC.Base
 import GHC.Classes
 
 default ()
diff --git a/libraries/base/GHC/Stack/Types.hs b/libraries/base/GHC/Stack/Types.hs
index 4c8a106ae5..45b11216a5 100644
--- a/libraries/base/GHC/Stack/Types.hs
+++ b/libraries/base/GHC/Stack/Types.hs
@@ -51,9 +51,9 @@ import GHC.Classes (Eq)
 import GHC.Types (Char, Int)
 
 -- Make implicit dependency known to build system
-import GHC.Tuple ()
-import GHC.Integer ()
-import GHC.Natural ()
+import GHC.Tuple ()   -- See Note [Depend on GHC.Tuple] in GHC.Base
+import GHC.Integer () -- See Note [Depend on GHC.Integer] in GHC.Base
+import GHC.Natural () -- See Note [Depend on GHC.Natural] in GHC.Base
 
 ----------------------------------------------------------------------
 -- Explicit call-stacks built via ImplicitParams
diff --git a/libraries/base/Unsafe/Coerce.hs b/libraries/base/Unsafe/Coerce.hs
index d9a7977e43..5bcbb01e1a 100644
--- a/libraries/base/Unsafe/Coerce.hs
+++ b/libraries/base/Unsafe/Coerce.hs
@@ -31,8 +31,8 @@
 
 module Unsafe.Coerce (unsafeCoerce) where
 
-import GHC.Integer () -- for build ordering
-import GHC.Natural () -- for build ordering
+import GHC.Integer () -- See Note [Depend on GHC.Integer] in GHC.Base
+import GHC.Natural () -- See Note [Depend on GHC.Natural] in GHC.Base
 import GHC.Prim (unsafeCoerce#)
 
 local_id :: a -> a