Add notes to ghc-prim Haddocks that users should not import it

8 files changed, 26 insertions, 1 deletions

diff --git a/libraries/ghc-prim/GHC/Classes.hs b/libraries/ghc-prim/GHC/Classes.hs
index 3ca06ac144..9b24ebcb16 100644
--- a/libraries/ghc-prim/GHC/Classes.hs
+++ b/libraries/ghc-prim/GHC/Classes.hs
@@ -27,6 +27,9 @@
 -- Portability :  non-portable (GHC extensions)
 --
 -- Basic classes.
+-- Do not import this module directly.  It is an GHC internal only
+-- module.  Some of its contents are instead available from @Prelude@
+-- and @GHC.Int@.
 --
 -----------------------------------------------------------------------------
 
@@ -35,6 +38,8 @@ module GHC.Classes(
     IP(..),
 
     -- * Equality and ordering
+    -- | Do not import these classes from this module. Import them
+    -- from @Prelude@ instead.
     Eq(..),
     Ord(..),
     -- ** Monomorphic equality operators
@@ -48,6 +53,8 @@ module GHC.Classes(
     gtWord, geWord, leWord, ltWord, compareWord, compareWord#,
 
     -- * Functions over Bool
+    -- | Do not import these functions from this module. Import them
+    -- from @Prelude@ instead.
     (&&), (||), not,
 
     -- * Integer arithmetic
diff --git a/libraries/ghc-prim/GHC/Debug.hs b/libraries/ghc-prim/GHC/Debug.hs
index ac8a0f5d79..2227607b4c 100644
--- a/libraries/ghc-prim/GHC/Debug.hs
+++ b/libraries/ghc-prim/GHC/Debug.hs
@@ -1,6 +1,8 @@
 {-# LANGUAGE Trustworthy #-}
 {-# LANGUAGE MagicHash, NoImplicitPrelude, UnboxedTuples, UnliftedFFITypes #-}
 
+-- | Users should not import this module.  It is GHC internal only.
+
 module GHC.Debug ( debugLn, debugErrLn ) where
 
 import GHC.Prim
diff --git a/libraries/ghc-prim/GHC/Prim/Exception.hs b/libraries/ghc-prim/GHC/Prim/Exception.hs
index 0b9e9c165c..5984dab09c 100644
--- a/libraries/ghc-prim/GHC/Prim/Exception.hs
+++ b/libraries/ghc-prim/GHC/Prim/Exception.hs
@@ -6,6 +6,8 @@
 {-# LANGUAGE EmptyCase #-}
 
 -- | Primitive exceptions.
+--
+-- Users should not import this module.  It is GHC internal only.
 module GHC.Prim.Exception
    ( raiseOverflow
    , raiseUnderflow
diff --git a/libraries/ghc-prim/GHC/Prim/Ext.hs b/libraries/ghc-prim/GHC/Prim/Ext.hs
index d911133947..f1eaa2dd45 100644
--- a/libraries/ghc-prim/GHC/Prim/Ext.hs
+++ b/libraries/ghc-prim/GHC/Prim/Ext.hs
@@ -18,6 +18,9 @@
 
 -- | Extra C-- routines exposed from the RTS
 --
+-- Users should not import this module.  It is GHC internal only.  Use
+-- "GHC.Conc" instead.
+--
 -- Actual primops are emitted by the compiler itself. They are special bits of
 -- code with backend support. The foreign functions in this module aren't actual
 -- primops because the compiler doesn't care about them at all: they just are
diff --git a/libraries/ghc-prim/GHC/Prim/Panic.hs b/libraries/ghc-prim/GHC/Prim/Panic.hs
index 0aa07813c1..a6f1eb588b 100644
--- a/libraries/ghc-prim/GHC/Prim/Panic.hs
+++ b/libraries/ghc-prim/GHC/Prim/Panic.hs
@@ -6,6 +6,8 @@
 {-# LANGUAGE EmptyCase #-}
 
 -- | Primitive panics.
+--
+-- Users should not import this module.  It is GHC internal only.
 module GHC.Prim.Panic
    ( absentSumFieldError
    , panicError
diff --git a/libraries/ghc-prim/GHC/Tuple.hs b/libraries/ghc-prim/GHC/Tuple.hs
index 9f4b70e6c1..78904f411e 100644
--- a/libraries/ghc-prim/GHC/Tuple.hs
+++ b/libraries/ghc-prim/GHC/Tuple.hs
@@ -12,6 +12,8 @@
 --
 -- The tuple data types
 --
+-- Users should not import this module.  It is GHC internal only.
+--
 -----------------------------------------------------------------------------
 
 module GHC.Tuple where
diff --git a/libraries/ghc-prim/ghc-prim.cabal b/libraries/ghc-prim/ghc-prim.cabal
index 678ee8801b..4755566663 100644
--- a/libraries/ghc-prim/ghc-prim.cabal
+++ b/libraries/ghc-prim/ghc-prim.cabal
@@ -12,6 +12,11 @@ build-type:     Custom
 description:
     This package contains the primitive types and operations supplied by GHC.
 
+    It is an internal package, only for the use of GHC developers.
+    GHC users should not use it!  If you do use it then expect
+    breaking changes at any time without warning.  You should prefer
+    to import @GHC.Exts@ from the @base@ package instead.
+
 extra-source-files: changelog.md
 
 source-repository head
diff --git a/utils/genprimopcode/Main.hs b/utils/genprimopcode/Main.hs
index 288ba325fb..1c06ea1bb6 100644
--- a/utils/genprimopcode/Main.hs
+++ b/utils/genprimopcode/Main.hs
@@ -446,7 +446,9 @@ In PrimopWrappers we set some crucial GHC options
 
 gen_wrappers :: Info -> String
 gen_wrappers (Info _ entries)
-   =    "{-# LANGUAGE MagicHash, NoImplicitPrelude, UnboxedTuples #-}\n"
+   =    "-- | Users should not import this module.  It is GHC internal only.\n"
+     ++ "-- Use \"GHC.Exts\" instead.\n"
+     ++ "{-# LANGUAGE MagicHash, NoImplicitPrelude, UnboxedTuples #-}\n"
         -- Dependencies on Prelude must be explicit in libraries/base, but we
         -- don't need the Prelude here so we add NoImplicitPrelude.
      ++ "{-# OPTIONS_GHC -Wno-deprecations -O0 -fno-do-eta-reduction #-}\n"