[commit: ghc] wip/tdammers/D4394: Documented invariant on cached roles (766ae47)

[git at git.haskell.org]

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

On branch  : wip/tdammers/D4394
Link       : http://ghc.haskell.org/trac/ghc/changeset/766ae4795c15ea70f3445c88de56a6ce9fa7c6ae/ghc

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

commit 766ae4795c15ea70f3445c88de56a6ce9fa7c6ae
Author: Tobias Dammers <tdammers at gmail.com>
Date:   Wed Feb 7 13:45:01 2018 +0100

    Documented invariant on cached roles


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

766ae4795c15ea70f3445c88de56a6ce9fa7c6ae
 compiler/types/TyCoRep.hs | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/compiler/types/TyCoRep.hs b/compiler/types/TyCoRep.hs
index b6ccc93..c32bdb6 100644
--- a/compiler/types/TyCoRep.hs
+++ b/compiler/types/TyCoRep.hs
@@ -857,7 +857,11 @@ data Coercion
     -- :: "e" _ -> e0 -> e (inverse of TyConAppCo, see Note [TyConAppCo roles])
     -- Using NthCo on a ForAllCo gives an N coercion always
     -- See Note [NthCo and newtypes]
+    --
+    -- Invariant:  (NthCo r i co), it is always the case that r = role of (Nth i co)
+    -- That is: the role of the entire coercion is redundantly cached here.
     -- See Note [NthCo Cached Roles]
+    --
     -- The Role might be more permissive than otherwise possible. That is, even
     -- if the Coercion inside is Nominal, the role could be Representational
     -- (it's like using a SubCo)