--- TyClDecls are precisely the kind of declarations that can
--- appear in interface files; or (internally) in GHC's interface
--- for a module. That's why (despite the misnomer) IfaceSig and ForeignType
--- are both in TyClDecl
+-- Representation of indexed types
+-- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+-- Family kind signatures are represented by the variant `TyFamily'. It
+-- covers "type family", "newtype family", and "data family" declarations,
+-- distinguished by the value of the field `tcdFlavour'.
+--
+-- Indexed types are represented by 'TyData' and 'TySynonym' using the field
+-- 'tcdTyPats::Maybe [LHsType name]', with the following meaning:
+--
+-- * If it is 'Nothing', we have a *vanilla* data type declaration or type
+-- synonym declaration and 'tcdVars' contains the type parameters of the
+-- type constructor.
+--
+-- * If it is 'Just pats', we have the definition of an indexed type. Then,
+-- 'pats' are type patterns for the type-indexes of the type constructor
+-- and 'tcdTyVars' are the variables in those patterns. Hence, the arity of
+-- the indexed type (ie, the number of indexes) is 'length tcdTyPats' and
+-- *not* 'length tcdVars'.
+--
+-- In both cases, 'tcdVars' collects all variables we need to quantify over.