[commit: ghc] wip/names3: Clarify Note [Fingerprinting IfaceDecls] (78b50a6)

[git at git.haskell.org]

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

On branch  : wip/names3
Link       : http://ghc.haskell.org/trac/ghc/changeset/78b50a62a406976f7c6cd20f990a0f7a34a93eaf/ghc

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

commit 78b50a62a406976f7c6cd20f990a0f7a34a93eaf
Author: Ben Gamari <ben at smart-cactus.org>
Date:   Thu Aug 25 15:22:00 2016 -0400

    Clarify Note [Fingerprinting IfaceDecls]


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

78b50a62a406976f7c6cd20f990a0f7a34a93eaf
 compiler/iface/MkIface.hs | 17 ++++++++++++-----
 1 file changed, 12 insertions(+), 5 deletions(-)

diff --git a/compiler/iface/MkIface.hs b/compiler/iface/MkIface.hs
index 077f243..358c813 100644
--- a/compiler/iface/MkIface.hs
+++ b/compiler/iface/MkIface.hs
@@ -375,13 +375,20 @@ Note [Fingerprinting IfaceDecls]
 The general idea here is that we first examine the 'IfaceDecl's and determine
 the recursive groups of them. We then walk these groups in dependency order,
 serializing each contained 'IfaceDecl' to a "Binary" buffer which we then
-hash using MD5 to produce a fingerprint for the group. However, the
-serialization that we use is a bit funny: we override the @putName@ operation
-with our own which serializes the hash of a 'Name' instead of the 'Name'
-itself. This ensures that the fingerprint of a decl changes if anything in its
-transitive closure changes. This trick is why we must be careful about
+hash using MD5 to produce a fingerprint for the group.
+
+However, the serialization that we use is a bit funny: we override the @putName@
+operation with our own which serializes the hash of a 'Name' instead of the
+'Name' itself. This ensures that the fingerprint of a decl changes if anything
+in its transitive closure changes. This trick is why we must be careful about
 traversing in dependency order: we need to ensure that we have hashes for
 everything referenced by the decl which we are fingerprinting.
+
+Moreover, we need to be careful to distinguish between serialization of binding
+Names (e.g. the ifName field of a IfaceDecl) and non-binding (e.g. the ifInstCls
+field of a IfaceClsInst): only in the non-binding case should we include the
+fingerprint; in the binding case we shouldn't since it is merely the name of the
+thing that we are currently fingerprinting.
 -}
 
 -- | Add fingerprints for top-level declarations to a 'ModIface'.