[Git][ghc/ghc][master] Add notes to ghc-prim Haddocks that users should not import it

[Marge Bot (@marge-bot)]

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


Commits:
6a8c6b5e by Tom Ellis at 2022-09-20T13:12:27-04:00
Add notes to ghc-prim Haddocks that users should not import it

- - - - -


8 changed files:

- libraries/ghc-prim/GHC/Classes.hs
- libraries/ghc-prim/GHC/Debug.hs
- libraries/ghc-prim/GHC/Prim/Exception.hs
- libraries/ghc-prim/GHC/Prim/Ext.hs
- libraries/ghc-prim/GHC/Prim/Panic.hs
- libraries/ghc-prim/GHC/Tuple.hs
- libraries/ghc-prim/ghc-prim.cabal
- utils/genprimopcode/Main.hs


Changes:

=====================================
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 at .
 --
 -----------------------------------------------------------------------------
 
@@ -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


=====================================
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


=====================================
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


=====================================
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


=====================================
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


=====================================
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


=====================================
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


=====================================
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"



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

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


-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.haskell.org/pipermail/ghc-commits/attachments/20220920/0fe6d52a/attachment-0001.html>