[commit: ghc] wip/nfs-locking: Revise comments (816b0ac)

[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/816b0acda7a57cdb3c7a88831b445bb17405975b/ghc

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

commit 816b0acda7a57cdb3c7a88831b445bb17405975b
Author: Andrey Mokhov <andrey.mokhov at gmail.com>
Date:   Thu May 19 23:39:15 2016 +0100

    Revise comments


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

816b0acda7a57cdb3c7a88831b445bb17405975b
 src/Oracles/ArgsHash.hs | 21 ++++++++++-----------
 1 file changed, 10 insertions(+), 11 deletions(-)

diff --git a/src/Oracles/ArgsHash.hs b/src/Oracles/ArgsHash.hs
index c26efd4..bb597c4 100644
--- a/src/Oracles/ArgsHash.hs
+++ b/src/Oracles/ArgsHash.hs
@@ -8,26 +8,25 @@ import Settings.Args
 import Target
 
 newtype ArgsHashKey = ArgsHashKey Target
-    deriving (Show, Eq, Typeable, Binary, Hashable, NFData)
+    deriving (Binary, Eq, Hashable, NFData, Show, Typeable)
 
--- This is an action that given a full target determines the corresponding
--- argument list and computes its hash. The resulting value is tracked in a
--- Shake oracle, hence initiating rebuilts when the hash is changed (a hash
--- change indicates changes in the build system).
+-- TODO: Hash Target to improve accuracy and performance.
+-- | Given a full target this Action determines the corresponding argument list
+-- and computes its hash. The resulting value is tracked in a Shake oracle,
+-- hence initiating rebuilds when the hash changes (a hash change indicates
+-- changes in the build command for the given target).
 -- Note: we keep only the first target input for performance reasons -- to
 -- avoid storing long lists of source files passed to some builders (e.g. Ar)
--- in the Shake database. This optimisation is harmless, because argument list
--- constructors are assumed not to examine target sources, but only append them
--- to argument lists where appropriate.
--- TODO: enforce the above assumption via type trickery?
--- TODO: Hash Target to improve accuracy and performance.
+-- in the Shake database. This optimisation is normally harmless, because
+-- argument list constructors are assumed not to examine target sources, but
+-- only append them to argument lists where appropriate.
 checkArgsHash :: Target -> Action ()
 checkArgsHash target = when trackBuildSystem $ do
     let hashed = [ show . hash $ inputs target ]
     _ <- askOracle . ArgsHashKey $ target { inputs = hashed } :: Action Int
     return ()
 
--- Oracle for storing per-target argument list hashes
+-- | Oracle for storing per-target argument list hashes.
 argsHashOracle :: Rules ()
 argsHashOracle = void $
     addOracle $ \(ArgsHashKey target) -> hash <$> interpret target getArgs