base: Add disclaimers in internal modules

To warn users that these modules are internal and their interfaces may
change with little warning.

As proposed in Core Libraries Committee #146 [CLC146].

[CLC146]: haskell/core-libraries-committee#146

Author: bgamari

libraries/base/GHC/Arr.hs

@@ -15,6 +15,11 @@
 --
 -- GHC\'s array implementation.
 --
+-- /The API of this module is unstable and not meant to be consumed by the general public./
+-- If you absolutely must depend on it, make sure to use a tight upper
+-- bound, e.g., @base < 4.X@ rather than @base < 5@, because the interface can
+-- change rapidly without much warning.
+--
 -----------------------------------------------------------------------------
 
 module GHC.Arr (

libraries/base/GHC/Conc.hs

@@ -6,7 +6,7 @@
 -----------------------------------------------------------------------------
 -- |
 -- Module      :  GHC.Conc
--- Copyright   :  (c) The University of Glasgow, 1994-2002
+-- Copyright   :  (c) The University of Glasgow, 1994-2023
 -- License     :  see libraries/base/LICENSE
 --
 -- Maintainer  :  [email protected]
@@ -15,6 +15,11 @@
 --
 -- Basic concurrency stuff.
 --
+-- /The API of this module is unstable and not meant to be consumed by the general public./
+-- If you absolutely must depend on it, make sure to use a tight upper
+-- bound, e.g., @base < 4.X@ rather than @base < 5@, because the interface can
+-- change rapidly without much warning.
+--
 -----------------------------------------------------------------------------
 
 -- No: #hide, because bits of this module are exposed by the stm package.

libraries/base/GHC/Conc/IO.hs

@@ -18,6 +18,11 @@
 --
 -- Basic concurrency stuff.
 --
+-- /The API of this module is unstable and not meant to be consumed by the general public./
+-- If you absolutely must depend on it, make sure to use a tight upper
+-- bound, e.g., @base < 4.X@ rather than @base < 5@, because the interface can
+-- change rapidly without much warning.
+--
 -----------------------------------------------------------------------------
 
 -- No: #hide, because bits of this module are exposed by the stm package.

libraries/base/GHC/Desugar.hs

@@ -17,6 +17,11 @@
 --
 -- Support code for desugaring in GHC
 --
+-- /The API of this module is unstable and not meant to be consumed by the general public./
+-- If you absolutely must depend on it, make sure to use a tight upper
+-- bound, e.g., @base < 4.X@ rather than @base < 5@, because the interface can
+-- change rapidly without much warning.
+--
 -----------------------------------------------------------------------------
 
 module GHC.Desugar ((>>>), AnnotationWrapper(..), toAnnotationWrapper) where

libraries/base/GHC/Encoding/UTF8.hs

@@ -2,7 +2,21 @@
 {-# LANGUAGE BangPatterns, MagicHash, UnboxedTuples, NoImplicitPrelude #-}
 {-# OPTIONS_GHC -O2 -fno-warn-name-shadowing #-}
 
--- | Simple UTF-8 codecs supporting non-streaming encoding/decoding.
+-- |
+-- Module      :  GHC.Encoding.UTF8
+-- Copyright   :  (c) The University of Glasgow, 1994-2023
+-- License     :  see libraries/base/LICENSE
+--
+-- Maintainer  :  [email protected]
+-- Stability   :  internal
+-- Portability :  non-portable (GHC extensions)
+--
+-- /The API of this module is unstable and not meant to be consumed by the general public./
+-- If you absolutely must depend on it, make sure to use a tight upper
+-- bound, e.g., @base < 4.X@ rather than @base < 5@, because the interface can
+-- change rapidly without much warning.
+--
+-- Simple UTF-8 codecs supporting non-streaming encoding/decoding.
 -- For encoding where codepoints may be broken across buffers,
 -- see "GHC.IO.Encoding.UTF8".
 --

libraries/base/GHC/Event/TimeOut.hs

@@ -11,6 +11,11 @@
 --
 -- Common Timer definitions shared between WinIO and RIO.
 --
+-- /The API of this module is unstable and not meant to be consumed by the general public./
+-- If you absolutely must depend on it, make sure to use a tight upper
+-- bound, e.g., @base < 4.X@ rather than @base < 5@, because the interface can
+-- change rapidly without much warning.
+--
 -------------------------------------------------------------------------------
 
 module GHC.Event.TimeOut where

libraries/base/GHC/Exception.hs

@@ -20,6 +20,11 @@
 --
 -- Exceptions and exception-handling functions.
 --
+-- /The API of this module is unstable and not meant to be consumed by the general public./
+-- If you absolutely must depend on it, make sure to use a tight upper
+-- bound, e.g., @base < 4.X@ rather than @base < 5@, because the interface can
+-- change rapidly without much warning.
+--
 -----------------------------------------------------------------------------
 
 module GHC.Exception

libraries/base/GHC/Exception/Type.hs

@@ -16,6 +16,11 @@
 --
 -- Exceptions and exception-handling functions.
 --
+-- /The API of this module is unstable and not meant to be consumed by the general public./
+-- If you absolutely must depend on it, make sure to use a tight upper
+-- bound, e.g., @base < 4.X@ rather than @base < 5@, because the interface can
+-- change rapidly without much warning.
+--
 -----------------------------------------------------------------------------
 
 module GHC.Exception.Type

libraries/base/GHC/ExecutionStack/Internal.hsc

@@ -8,7 +8,12 @@
 -- Stability   :  internal
 -- Portability :  non-portable (GHC Extensions)
 --
--- Internals of the `GHC.ExecutionStack` module
+-- Internals of the "GHC.ExecutionStack" module.
+--
+-- /The API of this module is unstable and not meant to be consumed by the general public./
+-- If you absolutely must depend on it, make sure to use a tight upper
+-- bound, e.g., @base < 4.X@ rather than @base < 5@, because the interface can
+-- change rapidly without much warning.
 --
 -- @since 4.9.0.0
 -----------------------------------------------------------------------------

libraries/base/GHC/Fingerprint/Type.hs

@@ -1,14 +1,22 @@
 {-# LANGUAGE Trustworthy #-}
 {-# LANGUAGE NoImplicitPrelude #-}
 
--- ----------------------------------------------------------------------------
+-- |
+-- Module      :  GHC.Fingerprint.Type
+-- Copyright   :  (c) The University of Glasgow, 1994-2023
+-- License     :  see libraries/base/LICENSE
 --
---  (c) The University of Glasgow 2006
+-- Maintainer  :  [email protected]
+-- Stability   :  internal
+-- Portability :  non-portable (GHC extensions)
 --
 -- Fingerprints for recompilation checking and ABI versioning, and
 -- implementing fast comparison of Typeable.
 --
--- ----------------------------------------------------------------------------
+-- /The API of this module is unstable and not meant to be consumed by the general public./
+-- If you absolutely must depend on it, make sure to use a tight upper
+-- bound, e.g., @base < 4.X@ rather than @base < 5@, because the interface can
+-- change rapidly without much warning.
 
 module GHC.Fingerprint.Type (Fingerprint(..)) where
 

libraries/base/GHC/Float/RealFracMethods.hs

@@ -15,7 +15,12 @@
 -- Methods for the RealFrac instances for 'Float' and 'Double',
 -- with specialised versions for 'Int'.
 --
--- Moved to their own module to not bloat GHC.Float further.
+-- Moved to their own module to not bloat "GHC.Float" further.
+--
+-- /The API of this module is unstable and not meant to be consumed by the general public./
+-- If you absolutely must depend on it, make sure to use a tight upper
+-- bound, e.g., @base < 4.X@ rather than @base < 5@, because the interface can
+-- change rapidly without much warning.
 --
 -----------------------------------------------------------------------------
 

libraries/base/GHC/GHCi.hs

@@ -15,6 +15,11 @@
 --
 -- EXPERIMENTAL! DON'T USE.
 --
+-- /The API of this module is unstable and not meant to be consumed by the general public./
+-- If you absolutely must depend on it, make sure to use a tight upper
+-- bound, e.g., @base < 4.X@ rather than @base < 5@, because the interface can
+-- change rapidly without much warning.
+--
 -----------------------------------------------------------------------------
 
 module GHC.GHCi {-# WARNING "This is an unstable interface." #-} (

libraries/base/GHC/GHCi/Helpers.hs

@@ -10,6 +10,11 @@
 --
 -- Various helpers used by the GHCi shell.
 --
+-- /The API of this module is unstable and not meant to be consumed by the general public./
+-- If you absolutely must depend on it, make sure to use a tight upper
+-- bound, e.g., @base < 4.X@ rather than @base < 5@, because the interface can
+-- change rapidly without much warning.
+--
 -----------------------------------------------------------------------------
 
 module GHC.GHCi.Helpers

libraries/base/GHC/IO.hs

@@ -12,7 +12,7 @@
 -----------------------------------------------------------------------------
 -- |
 -- Module      :  GHC.IO
--- Copyright   :  (c) The University of Glasgow 1994-2002
+-- Copyright   :  (c) The University of Glasgow 1994-2023
 -- License     :  see libraries/base/LICENSE
 --
 -- Maintainer  :  [email protected]
@@ -21,6 +21,11 @@
 --
 -- Definitions for the 'IO' monad and its friends.
 --
+-- /The API of this module is unstable and not meant to be consumed by the general public./
+-- If you absolutely must depend on it, make sure to use a tight upper
+-- bound, e.g., @base < 4.X@ rather than @base < 5@, because the interface can
+-- change rapidly without much warning.
+--
 -----------------------------------------------------------------------------
 
 module GHC.IO (

libraries/base/GHC/IO/Buffer.hs

@@ -14,6 +14,11 @@
 --
 -- Buffers used in the IO system
 --
+-- /The API of this module is unstable and not meant to be consumed by the general public./
+-- If you absolutely must depend on it, make sure to use a tight upper
+-- bound, e.g., @base < 4.X@ rather than @base < 5@, because the interface can
+-- change rapidly without much warning.
+--
 -----------------------------------------------------------------------------
 
 module GHC.IO.Buffer (

libraries/base/GHC/IO/Device.hs

@@ -13,6 +13,11 @@
 --
 -- Type classes for I/O providers.
 --
+-- /The API of this module is unstable and not meant to be consumed by the general public./
+-- If you absolutely must depend on it, make sure to use a tight upper
+-- bound, e.g., @base < 4.X@ rather than @base < 5@, because the interface can
+-- change rapidly without much warning.
+--
 -----------------------------------------------------------------------------
 
 module GHC.IO.Device (

libraries/base/GHC/IO/Encoding.hs

@@ -15,6 +15,11 @@
 --
 -- Text codecs for I/O
 --
+-- /The API of this module is unstable and not meant to be consumed by the general public./
+-- If you absolutely must depend on it, make sure to use a tight upper
+-- bound, e.g., @base < 4.X@ rather than @base < 5@, because the interface can
+-- change rapidly without much warning.
+--
 -----------------------------------------------------------------------------
 
 module GHC.IO.Encoding (

libraries/base/GHC/IO/Exception.hs

@@ -16,6 +16,11 @@
 --
 -- IO-related Exception types and functions
 --
+-- /The API of this module is unstable and not meant to be consumed by the general public./
+-- If you absolutely must depend on it, make sure to use a tight upper
+-- bound, e.g., @base < 4.X@ rather than @base < 5@, because the interface can
+-- change rapidly without much warning.
+--
 -----------------------------------------------------------------------------
 
 module GHC.IO.Exception (

libraries/base/GHC/IO/Handle/Internals.hs

@@ -24,6 +24,11 @@
 -- of the operations defined here are independent of the underlying
 -- device.
 --
+-- /The API of this module is unstable and not meant to be consumed by the general public./
+-- If you absolutely must depend on it, make sure to use a tight upper
+-- bound, e.g., @base < 4.X@ rather than @base < 5@, because the interface can
+-- change rapidly without much warning.
+--
 -----------------------------------------------------------------------------
 
 module GHC.IO.Handle.Internals (

libraries/base/GHC/IO/Handle/Text.hs

@@ -22,6 +22,11 @@
 --
 -- String I\/O functions
 --
+-- /The API of this module is unstable and not meant to be consumed by the general public./
+-- If you absolutely must depend on it, make sure to use a tight upper
+-- bound, e.g., @base < 4.X@ rather than @base < 5@, because the interface can
+-- change rapidly without much warning.
+--
 -----------------------------------------------------------------------------
 
 module GHC.IO.Handle.Text (

libraries/base/GHC/IO/Handle/Types.hs

@@ -18,6 +18,11 @@
 --
 -- Basic types for the implementation of IO Handles.
 --
+-- /The API of this module is unstable and not meant to be consumed by the general public./
+-- If you absolutely must depend on it, make sure to use a tight upper
+-- bound, e.g., @base < 4.X@ rather than @base < 5@, because the interface can
+-- change rapidly without much warning.
+--
 -----------------------------------------------------------------------------
 
 module GHC.IO.Handle.Types (

libraries/base/GHC/IO/SubSystem.hs

@@ -12,9 +12,14 @@
 -- Stability   :  internal
 -- Portability :  non-portable
 --
--- The SubSystem control interface.  These methods can be used to disambiguate
+-- The 'IoSubSystem' control interface.  These methods can be used to disambiguate
 -- between the two operations.
 --
+-- /The API of this module is unstable and not meant to be consumed by the general public./
+-- If you absolutely must depend on it, make sure to use a tight upper
+-- bound, e.g., @base < 4.X@ rather than @base < 5@, because the interface can
+-- change rapidly without much warning.
+--
 -----------------------------------------------------------------------------
 
 module GHC.IO.SubSystem (

libraries/base/GHC/IOPort.hs

@@ -13,7 +13,13 @@
 -- Stability   :  internal
 -- Portability :  non-portable (GHC Extensions)
 --
--- The IOPort type. This is a facility used by the Windows IO subsystem.
+-- The 'IOPort' type. This is a facility used by the Windows IO subsystem.
+--
+-- /The API of this module is unstable and not meant to be consumed by the general public./
+-- If you absolutely must depend on it, make sure to use a tight upper
+-- bound, e.g., @base < 4.X@ rather than @base < 5@, because the interface can
+-- change rapidly without much warning.
+--
 -- We have strict rules with an I/O Port:
 -- * writing more than once is an error
 -- * reading more than once is an error

libraries/base/GHC/InfoProv.hsc

@@ -15,6 +15,11 @@
 --
 -- Access to GHC's info-table provenance metadata.
 --
+-- /The API of this module is unstable and not meant to be consumed by the general public./
+-- If you absolutely must depend on it, make sure to use a tight upper
+-- bound, e.g., @base < 4.X@ rather than @base < 5@, because the interface can
+-- change rapidly without much warning.
+--
 -- @since 4.18.0.0
 -----------------------------------------------------------------------------
 

libraries/base/GHC/RTS/Flags.hsc

@@ -1,7 +1,19 @@
 {-# LANGUAGE DeriveGeneric #-}
 {-# LANGUAGE NoImplicitPrelude #-}
 
--- | Accessors to GHC RTS flags.
+-- |
+-- Module      :  GHC.RTS.Flags
+-- Copyright   :  (c) The University of Glasgow, 1994-2000
+-- License     :  see libraries/base/LICENSE
+--
+-- Maintainer  :  [email protected]
+-- Stability   :  internal
+-- Portability :  non-portable (GHC extensions)
+--
+-- /The API of this module is unstable and is tightly coupled to GHC's internals./
+-- If depend on it, make sure to use a tight upper bound, e.g., @base < 4.X@ rather
+-- than @base < 5@, because the interface can change rapidly without much warning.
+--
 -- Descriptions of flags can be seen in
 -- <https://www.haskell.org/ghc/docs/latest/html/users_guide/runtime_control.html GHC User's Guide>,
 -- or by running RTS help message using @+RTS --help@.

libraries/base/GHC/Stack/Types.hs

@@ -19,10 +19,15 @@
 -- Stability   :  internal
 -- Portability :  non-portable (GHC Extensions)
 --
--- type definitions for implicit call-stacks.
+-- Type definitions for implicit call-stacks.
 -- Use "GHC.Stack" from the base package instead of importing this
 -- module directly.
 --
+-- /The API of this module is unstable and not meant to be consumed by the general public./
+-- If you absolutely must depend on it, make sure to use a tight upper
+-- bound, e.g., @base < 4.X@ rather than @base < 5@, because the interface can
+-- change rapidly without much warning.
+--
 -----------------------------------------------------------------------------
 
 module GHC.Stack.Types (