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

[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/1ef2070b30258e40c1f651d6959e89c680b06d98/ghc

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

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

    Documented invariant on cached roles


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

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

diff --git a/compiler/types/TyCoRep.hs b/compiler/types/TyCoRep.hs
index cd295f7..1b25e0c 100644
--- a/compiler/types/TyCoRep.hs
+++ b/compiler/types/TyCoRep.hs
@@ -912,7 +912,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)