Comments about silent superclasses

compiler/basicTypes/IdInfo.lhs

@@ -142,7 +142,7 @@ data IdDetails
        --             instance C a => C [a]
        --       has is_silent = 1, because the dfun
        --       has type  dfun :: (D a, C a) => C [a]
-       --       See the DFun Superclass Invariant in TcInstDcls
+       --       See Note [Silent superclass arguments] in TcInstDcls
        --
        -- Bool = True <=> the class has only one method, so may be
        --                  implemented with a newtype, so it might be bad

compiler/typecheck/TcInstDcls.lhs

@@ -947,7 +947,7 @@ immediate superclasses of the dictionary we are trying to
 construct. In our example:
        dfun :: forall a. C [a] -> D [a] -> D [a]
        dfun = \(dc::C [a]) (dd::D [a]) -> DOrd dc ...
-Notice teh extra (dc :: C [a]) argument compared to the previous version.
+Notice the extra (dc :: C [a]) argument compared to the previous version.
 
 This gives us:
 
@@ -967,9 +967,13 @@ dictionary constructor). No superclass is hidden inside a dfun
 application.
 
 The extra arguments required to satisfy the DFun Superclass Invariant
-always come first, and are called the "silent" arguments.  DFun types
-are built (only) by MkId.mkDictFunId, so that is where we decide
-what silent arguments are to be added.
+always come first, and are called the "silent" arguments.  You can
+find out how many silent arguments there are using Id.dfunNSilent;
+and then you can just drop that number of arguments to see the ones
+that were in the original instance declaration.
+
+DFun types are built (only) by MkId.mkDictFunId, so that is where we
+decide what silent arguments are to be added.
 
 In our example, if we had  [Wanted] dw :: D [a] we would get via the instance:
     dw := dfun d1 d2

compiler/types/InstEnv.lhs

@@ -61,6 +61,10 @@ data ClsInst
                 --      forall is_tvs. (...) => is_cls is_tys
 
              , is_dfun :: DFunId -- See Note [Haddock assumptions]
+                    -- See Note [Silent superclass arguments] in TcInstDcls
+                    -- for how to map the DFun's type back to the source
+                    -- language instance decl
+
              , is_flag :: OverlapFlag   -- See detailed comments with
                                         -- the decl of BasicTypes.OverlapFlag
     }
@@ -159,6 +163,7 @@ pprInstanceHdr (ClsInst { is_flag = flag, is_dfun = dfun })
     let theta_to_print
           | debugStyle sty = theta
           | otherwise = drop (dfunNSilent dfun) theta
+          -- See Note [Silent superclass arguments] in TcInstDcls
     in ptext (sLit "instance") <+> ppr flag
        <+> sep [pprThetaArrowTy theta_to_print, ppr res_ty]
   where