Document the Generic(1) laws
authorRyan Scott <ryan.gl.scott@gmail.com>
Sat, 2 Sep 2017 19:33:34 +0000 (15:33 -0400)
committerRyan Scott <ryan.gl.scott@gmail.com>
Sat, 2 Sep 2017 19:33:34 +0000 (15:33 -0400)
Summary:
Some code that @dfeuer was writing implicitly depended on these laws,
but they didn't appear to be enshrined in the Haddocks. Let's do so.

Test Plan: Read it

Reviewers: austin, hvr, bgamari, dfeuer

Reviewed By: dfeuer

Subscribers: rwbarton, thomie, dfeuer

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

libraries/base/GHC/Generics.hs

index d4e9583..5bc9c55 100644 (file)
@@ -1147,8 +1147,15 @@ instance (SingI mn, SingI su, SingI ss, SingI ds)
   selSourceStrictness   _ = fromSing (sing :: Sing ss)
   selDecidedStrictness  _ = fromSing (sing :: Sing ds)
 
--- | Representable types of kind *.
--- This class is derivable in GHC with the DeriveGeneric flag on.
+-- | Representable types of kind @*@.
+-- This class is derivable in GHC with the @DeriveGeneric@ flag on.
+--
+-- A 'Generic' instance must satisfy the following laws:
+--
+-- @
+-- 'from' . 'to' ≡ 'id'
+-- 'to' . 'from' ≡ 'id'
+-- @
 class Generic a where
   -- | Generic representation type
   type Rep a :: * -> *
@@ -1161,6 +1168,13 @@ class Generic a where
 -- | Representable types of kind @* -> *@ (or kind @k -> *@, when @PolyKinds@
 -- is enabled).
 -- This class is derivable in GHC with the @DeriveGeneric@ flag on.
+--
+-- A 'Generic1' instance must satisfy the following laws:
+--
+-- @
+-- 'from1' . 'to1' ≡ 'id'
+-- 'to1' . 'from1' ≡ 'id'
+-- @
 class Generic1 (f :: k -> *) where
   -- | Generic representation type
   type Rep1 f :: k -> *