[commit: ghc] master: Add a Note describing #14128 (6f1ccaa)

[git at git.haskell.org]

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

On branch  : master
Link       : http://ghc.haskell.org/trac/ghc/changeset/6f1ccaa50f905bdc586a7a92ab7e38e30c1e7ff5/ghc

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

commit 6f1ccaa50f905bdc586a7a92ab7e38e30c1e7ff5
Author: Ben Gamari <ben at smart-cactus.org>
Date:   Tue Aug 29 19:14:22 2017 -0400

    Add a Note describing #14128
    
    I prematurely committed the D3892 before adding a Note. Fix this.


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

6f1ccaa50f905bdc586a7a92ab7e38e30c1e7ff5
 compiler/deSugar/DsUsage.hs | 21 ++++++++++++++++++++-
 1 file changed, 20 insertions(+), 1 deletion(-)

diff --git a/compiler/deSugar/DsUsage.hs b/compiler/deSugar/DsUsage.hs
index 3f302fa..6219804 100644
--- a/compiler/deSugar/DsUsage.hs
+++ b/compiler/deSugar/DsUsage.hs
@@ -26,6 +26,25 @@ import Data.Map (Map)
 import qualified Data.Map as Map
 import qualified Data.Set as Set
 
+{- Note [Module self-dependency]
+   ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+RnNames.calculateAvails asserts the invariant that a module must not occur in
+its own dep_orphs or dep_finsts. However, if we aren't careful this can occur
+in the presence of hs-boot files: Consider that we have two modules, A and B,
+both with hs-boot files,
+
+    A.hs contains a SOURCE import of B B.hs-boot contains a SOURCE import of A
+    A.hs-boot declares an orphan instance A.hs defines the orphan instance
+
+In this case, B's dep_orphs will contain A due to its SOURCE import of A.
+Consequently, A will contain itself in its imp_orphs due to its import of B.
+This fact would end up being recorded in A's interface file. This would then
+break the invariant asserted by calculateAvails that a module does not itself in
+its dep_orphs. This was the cause of Trac #14128.
+
+-}
+
 -- | Extract information from the rename and typecheck phases to produce
 -- a dependencies information for the module being compiled.
 mkDependencies :: TcGblEnv -> IO Dependencies
@@ -48,7 +67,7 @@ mkDependencies
 
           dep_orphs = filter (/= mod) (imp_orphs imports)
                 -- We must also remove self-references from imp_orphs. See
-                -- #14128.
+                -- Note [Module self-dependency]
 
           pkgs | th_used   = Set.insert (toInstalledUnitId thUnitId) (imp_dep_pkgs imports)
                | otherwise = imp_dep_pkgs imports