-We need to be careful with the handling of the type constructor of each type
-instance as the family constructor is already defined, and we want to avoid
-raising a duplicate declaration error. So, we make a new name for it, but
-don't return it in the 'AvailInfo'.
+Note [Looking up family names in family instances]
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Consider
+
+ module M where
+ type family T a :: *
+ type instance M.T Int = Bool
+
+We might think that we can simply use 'lookupOccRn' when processing the type
+instance to look up 'M.T'. Alas, we can't! The type family declaration is in
+the *same* HsGroup as the type instance declaration. Hence, as we are
+currently collecting the binders declared in that HsGroup, these binders will
+not have been added to the global environment yet.
+
+In the case of type classes, this problem does not arise, as a class instance
+does not define any binders of it's own. So, we simply don't attempt to look
+up the class names of class instances in 'get_local_binders' below.
+
+If we don't look up class instances, can't we get away without looking up type
+instances, too? No, we can't. Data type instances define data constructors
+and we need to
+
+ (1) collect those in 'get_local_binders' and
+ (2) we need to get their parent name in 'get_local_binders', too, to
+ produce an appropriate 'AvailTC'.
+
+This parent name is exactly the family name of the type instance that is so
+difficult to look up.
+
+We solve this problem as follows:
+
+ (a) We process all type declarations other than type instances first.
+ (b) Then, we compute a 'GlobalRdrEnv' from the result of the first step.
+ (c) Finally, we process all type instances (both those on the toplevel and
+ those nested in class instances) and check for the family names in the
+ 'GlobalRdrEnv' produced in the previous step before using 'lookupOccRn'.