[commit: ghc] master: Document the Generic(1) laws (0ec4376)

[git at git.haskell.org]

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

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

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

commit 0ec4376902ee88a77a9f2ac9f3c03a4432455320
Author: Ryan Scott <ryan.gl.scott at gmail.com>
Date:   Sat Sep 2 15:33:34 2017 -0400

    Document the Generic(1) laws
    
    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


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

0ec4376902ee88a77a9f2ac9f3c03a4432455320
 libraries/base/GHC/Generics.hs | 18 ++++++++++++++++--
 1 file changed, 16 insertions(+), 2 deletions(-)

diff --git a/libraries/base/GHC/Generics.hs b/libraries/base/GHC/Generics.hs
index d4e9583..5bc9c55 100644
--- a/libraries/base/GHC/Generics.hs
+++ b/libraries/base/GHC/Generics.hs
@@ -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 -> *