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

[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/be4891f72a7aa345e2c50e73e50676296d7534e0/ghc

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

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

    Documented invariant on cached roles


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

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

diff --git a/compiler/types/TyCoRep.hs b/compiler/types/TyCoRep.hs
index c719b31..32fdfaa 100644
--- a/compiler/types/TyCoRep.hs
+++ b/compiler/types/TyCoRep.hs
@@ -833,7 +833,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)