[commit: ghc] master: Document a law for TH's Lift class (626f045)

[git at git.haskell.org]

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

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

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

commit 626f0454ef1ca8f40c38064197dba97a36d52dbb
Author: Ryan Scott <ryan.gl.scott at gmail.com>
Date:   Fri Sep 29 23:32:41 2017 -0400

    Document a law for TH's Lift class
    
    Inspired by the discussion in #14296, I've decided to
    document a law which is usually in the back of my mind when I'm using
    Template Haskell's `Lift` class, but isn't formally stated anywhere.
    That is, every `Lift` instance should satisfy (for all `x`):
    
    ```lang=haskell
    $(lift x) == x
    ```
    
    Test Plan: Read it
    
    Reviewers: austin, goldfire, bgamari
    
    Subscribers: rwbarton, thomie
    
    Differential Revision: https://phabricator.haskell.org/D4050


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

626f0454ef1ca8f40c38064197dba97a36d52dbb
 libraries/template-haskell/Language/Haskell/TH/Syntax.hs | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/libraries/template-haskell/Language/Haskell/TH/Syntax.hs b/libraries/template-haskell/Language/Haskell/TH/Syntax.hs
index 419d944..0541a08 100644
--- a/libraries/template-haskell/Language/Haskell/TH/Syntax.hs
+++ b/libraries/template-haskell/Language/Haskell/TH/Syntax.hs
@@ -565,6 +565,9 @@ sequenceQ = sequence
 -- Template Haskell has no way of knowing what value @x@ will take on at
 -- splice-time, so it requires the type of @x@ to be an instance of 'Lift'.
 --
+-- A 'Lift' instance must satisfy @$(lift x) ≡ x@ for all @x@, where @$(...)@
+-- is a Template Haskell splice.
+--
 -- 'Lift' instances can be derived automatically by use of the @-XDeriveLift@
 -- GHC language extension:
 --