--- the following form.
---
-data AlgTyConParent = -- An ordinary type constructor has no parent.
- NoParentTyCon
-
- -- Type constructors representing a class dictionary.
- | ClassTyCon Class
-
- -- Type constructors representing an instances of a type
- -- family.
- | FamilyTyCon TyCon -- the type family
- [Type] -- instance types
- TyCon -- a *coercion* identifying
- -- the representation type
- -- with the type instance
-
+-- the following form. We use 'TyConParent' for both algebraic and synonym
+-- types, but the variant 'ClassTyCon' will only be used by algebraic 'TyCon's.
+data TyConParent
+ = -- | An ordinary type constructor has no parent.
+ NoParentTyCon
+
+ -- | Type constructors representing a class dictionary.
+ | ClassTyCon
+ Class -- INVARIANT: the classTyCon of this Class is the current tycon
+
+ -- | Type constructors representing an instance of a type family. Parameters:
+ --
+ -- 1) The type family in question
+ --
+ -- 2) Instance types; free variables are the 'tyConTyVars'
+ -- of the current 'TyCon' (not the family one). INVARIANT:
+ -- the number of types matches the arity of the family 'TyCon'
+ --
+ -- 3) A 'CoercionTyCon' identifying the representation
+ -- type with the type instance family
+ | FamilyTyCon
+ TyCon
+ [Type]
+ TyCon -- c.f. Note [Newtype coercions]
+
+ --
+ -- E.g. data intance T [a] = ...
+ -- gives a representation tycon:
+ -- data :R7T a = ...
+ -- axiom co a :: T [a] ~ :R7T a
+ -- with :R7T's algTcParent = FamilyTyCon T [a] co
+
+-- | Checks the invariants of a 'TyConParent' given the appropriate type class name, if any
+okParent :: Name -> TyConParent -> Bool
+okParent _ NoParentTyCon = True
+okParent tc_name (ClassTyCon cls) = tyConName (classTyCon cls) == tc_name
+okParent _ (FamilyTyCon fam_tc tys _co_tc) = tyConArity fam_tc == length tys
+
+--------------------
+
+-- | Information pertaining to the expansion of a type synonym (@type@)