[commit: ghc] wip/nfs-locking: Add comments. (e1d05c5)

[git at git.haskell.org]

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

On branch  : wip/nfs-locking
Link       : http://ghc.haskell.org/trac/ghc/changeset/e1d05c561f1ab7d939dc4decf5ca143a3bd07a5e/ghc

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

commit e1d05c561f1ab7d939dc4decf5ca143a3bd07a5e
Author: Andrey Mokhov <andrey.mokhov at gmail.com>
Date:   Fri Feb 19 00:35:44 2016 +0000

    Add comments.
    
    See #210.


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

e1d05c561f1ab7d939dc4decf5ca143a3bd07a5e
 src/Oracles/ModuleFiles.hs | 10 ++++++++++
 1 file changed, 10 insertions(+)

diff --git a/src/Oracles/ModuleFiles.hs b/src/Oracles/ModuleFiles.hs
index d8b1ae7..b831f76 100644
--- a/src/Oracles/ModuleFiles.hs
+++ b/src/Oracles/ModuleFiles.hs
@@ -37,6 +37,16 @@ haskellModuleFiles stage pkg = do
 
     return (haskellFiles, missingMods ++ map otherFileToMod otherFiles)
 
+-- | This is an important oracle whose role is to find and cache module source
+-- files. More specifically, it takes a list of module names @modules@ and a
+-- list of directories @dirs@ as arguments, and computes a sorted list of pairs
+-- of the form @(A.B.C, dir/A/B/C.extension)@, such that @A.B.C@ belongs to
+-- @modules@, @dir@ belongs to @dirs@, and file @dir/A/B/C.extension@ exists.
+-- For example, for 'compiler' package given
+-- @modules = ["CodeGen.Platform.ARM", "Lexer"]@, and
+-- @dirs = ["codeGen", "parser"]@, it produces
+-- @[("CodeGen.Platform.ARM", "codeGen/CodeGen/Platform/ARM.hs"),
+-- ("Lexer", "parser/Lexer.x")]@.
 moduleFilesOracle :: Rules ()
 moduleFilesOracle = void $
     addOracle $ \(ModuleFilesKey (modules, dirs)) -> do