base: Documentation for TypeError

Test Plan: Read

Reviewers: yav, hvr, austin

Reviewed By: austin

Subscribers: thomie

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

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

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
 
 

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