[commit: ghc] master: base: Documentation for TypeError (c945c90)

[git at git.haskell.org]

Repository : ssh://git@git.haskell.org/ghc

On branch  : master
Link       : http://ghc.haskell.org/trac/ghc/changeset/c945c90bd910b7e38abd2f98af7783eea281d8f8/ghc

>---------------------------------------------------------------

commit c945c90bd910b7e38abd2f98af7783eea281d8f8
Author: Ben Gamari <bgamari.foss at gmail.com>
Date:   Wed Nov 18 12:22:58 2015 +0100

    base: Documentation for TypeError
    
    Test Plan: Read
    
    Reviewers: yav, hvr, austin
    
    Reviewed By: austin
    
    Subscribers: thomie
    
    Differential Revision: https://phabricator.haskell.org/D1490


>---------------------------------------------------------------

c945c90bd910b7e38abd2f98af7783eea281d8f8
 docs/users_guide/7.12.1-notes.rst |  2 ++
 libraries/base/GHC/TypeLits.hs    | 26 ++++++++++++++++++++++++++
 libraries/base/changelog.md       |  3 +++
 3 files changed, 31 insertions(+)

diff --git a/docs/users_guide/7.12.1-notes.rst b/docs/users_guide/7.12.1-notes.rst
index 10ed77e..d52b066 100644
--- a/docs/users_guide/7.12.1-notes.rst
+++ b/docs/users_guide/7.12.1-notes.rst
@@ -227,6 +227,8 @@ base
   ``Applicative``. If this causes performance regressions, try to make the
   implementation of ``(*>)`` match that of ``(>>)``.
 
+- Add ``GHC.TypeLits.TypeError`` and ``ErrorMessage`` to allow users
+  to define custom compile-time error messages.
 
 binary
 ~~~~~~
diff --git a/libraries/base/GHC/TypeLits.hs b/libraries/base/GHC/TypeLits.hs
index f124017..0d9f4fe 100644
--- a/libraries/base/GHC/TypeLits.hs
+++ b/libraries/base/GHC/TypeLits.hs
@@ -215,6 +215,32 @@ data {-kind-} ErrorMessage = Text Symbol
 infixl 5 :$$:
 infixl 6 :<>:
 
+-- | The type-level equivalent of 'error'.
+--
+-- The polymorphic kind of this type allows it to be used in several settings.
+-- For instance, it can be used as a constraint, e.g. to provide a better error
+-- message for a non-existant instance,
+--
+-- @@
+-- -- in a context
+-- instance TypeError (Text "Cannot 'Show' functions." :$$:
+--                     Text "Perhaps there is a missing argument?")
+--       => Show (a -> b) where
+--     showsPrec = error "unreachable"
+-- @@
+--
+-- It can also be placed on the right-hand side of a type-level function
+-- to provide an error for an invalid case,
+--
+-- @@
+-- type family ByteSize x where
+--    ByteSize Word16   = 2
+--    ByteSize Word8    = 1
+--    ByteSize a        = TypeError (Text "The type " :<>: ShowType a :<>:
+--                                   Text " is not exportable.")
+-- @@
+--
+-- @since 4.9.0.0
 type family TypeError (a :: ErrorMessage) :: b where
 
 
diff --git a/libraries/base/changelog.md b/libraries/base/changelog.md
index 74692a7..f7718fa 100644
--- a/libraries/base/changelog.md
+++ b/libraries/base/changelog.md
@@ -91,6 +91,9 @@
   * Add `MonadPlus IO` and `Alternative IO` instances
     (previously orphans in `transformers`) (#10755)
 
+  * Add `GHC.TypeLits.TypeError` and `ErrorMessage` to allow users
+    to define custom compile-time error messages.
+
 ## 4.8.2.0  *Oct 2015*
 
   * Bundled with GHC 7.10.3