[commit: ghc] wip/T14880-2-step2-c123: Document TyCoRep changes better (1681eac)

[git at git.haskell.org]

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

On branch  : wip/T14880-2-step2-c123
Link       : http://ghc.haskell.org/trac/ghc/changeset/1681eac12f2931e1bbd5e4ad86f0aa3239d09505/ghc

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

commit 1681eac12f2931e1bbd5e4ad86f0aa3239d09505
Author: Tobias Dammers <tdammers at gmail.com>
Date:   Wed Oct 10 14:01:52 2018 +0200

    Document TyCoRep changes better


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

1681eac12f2931e1bbd5e4ad86f0aa3239d09505
 compiler/types/TyCoRep.hs | 23 ++++++++++++++++++++---
 1 file changed, 20 insertions(+), 3 deletions(-)

diff --git a/compiler/types/TyCoRep.hs b/compiler/types/TyCoRep.hs
index 3495387..4fb6b1c 100644
--- a/compiler/types/TyCoRep.hs
+++ b/compiler/types/TyCoRep.hs
@@ -1627,6 +1627,8 @@ so we profiled several versions, exploring different implementation strategies.
    "in-scope set" filter found in the internals of FV, but without the
    determinism overhead.
 
+See Trac #14880.
+
 -}
 
 tyCoVarsOfType :: Type -> TyCoVarSet
@@ -1721,9 +1723,6 @@ mkTyCoInScopeSet tys cos
   = mkInScopeSet (ty_co_vars_of_types tys emptyVarSet $
                   ty_co_vars_of_cos   cos emptyVarSet emptyVarSet)
 
---------------------- End of accumulator version  ----------------
------------------------------------------------------------------
-
 -- | `tyCoFVsOfType` that returns free variables of a type in a deterministic
 -- set. For explanation of why using `VarSet` is not deterministic see
 -- Note [Deterministic FV] in FV.
@@ -1857,6 +1856,24 @@ tyCoFVsOfCos (co:cos) fv_cand in_scope acc = (tyCoFVsOfCo co `unionFV` tyCoFVsOf
 
 ------------- Extracting the CoVars of a type or coercion -----------
 
+{-
+
+Note [CoVarsOfX and the InterestingVarFun]
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The coVarsOfType, coVarsOfTypes, coVarsOfCo, and coVarsOfCos functions are
+implemented in terms of the respective FV equivalents (tyCoFVsOf...), rather
+than the VarSet-based flavors (tyCoVarsOf...), despite the performance
+considerations outlined in Note [Free variables of types].
+
+This is because FV includes the InterestingVarFun, which is useful here,
+because we can cleverly use it to restrict our calculations to CoVars - this
+is what getCoVarSet achieves.
+
+See Trac #14880.
+
+-}
+
 getCoVarSet :: FV -> CoVarSet
 getCoVarSet fv = snd (fv isCoVar emptyVarSet ([], emptyVarSet))