hadrian: Update comments on verbosity handling

2 files changed, 14 insertions, 2 deletions

diff --git a/hadrian/src/Builder.hs b/hadrian/src/Builder.hs
index 4e488504ac..c746f95695 100644
--- a/hadrian/src/Builder.hs
+++ b/hadrian/src/Builder.hs
@@ -426,7 +426,7 @@ applyPatch dir patch = do
     putBuild $ "| Apply patch " ++ file
     quietly $ cmd' [Cwd dir, FileStdin file] [path, "-p0"]
 
--- | Wrapper for 'cmd' that makes sure we include both stdout and stderr in
---   Shake's output when any of our builder commands fail.
+-- | Wrapper for 'cmd' that suppresses the double reporting of StdErr and
+-- Stdout when a command fails.
 cmd' :: (Partial, CmdArguments args) => args :-> Action r
 cmd' = cmd [WithStderr False, WithStdout False]
diff --git a/hadrian/src/Main.hs b/hadrian/src/Main.hs
index bba30dfaa8..7fc15e245b 100644
--- a/hadrian/src/Main.hs
+++ b/hadrian/src/Main.hs
@@ -100,6 +100,10 @@ main = do
             Rules.topLevelTargets
             Rules.toolArgsTarget
 
+    -- This IORef is used to communicate the result of shake parsing
+    -- command line options (which happens in shakeArgsOptionsWith, but
+    -- isn't exposed to the user) to the exception handler, which uses the
+    -- verbosity and colour information to decide how much of the error to display.
     shake_opts_var <- newIORef options
     handleShakeException shake_opts_var $ shakeArgsOptionsWith options CommandLine.optDescrs $ \shake_opts _ targets -> do
         writeIORef  shake_opts_var shake_opts
@@ -112,6 +116,10 @@ main = do
 handleShakeException :: IORef ShakeOptions -> IO a -> IO a
 handleShakeException shake_opts_var shake_run = do
   args <- getArgs
+  -- Using withArgs here is a bit of a hack but the API doesn't allow another way
+  -- See https://github.com/ndmitchell/shake/issues/811
+  -- Passing --exception means shake throws an exception rather than
+  -- catching ShakeException and displaying the error itself to the user.
   catch (withArgs ("--exception" : args) $ shake_run) $ \(_e :: ShakeException) -> do
     shake_opts <- readIORef shake_opts_var
     let
@@ -121,6 +129,10 @@ handleShakeException shake_opts_var shake_run = do
       then
         hPrint stderr _e
       else
+        -- The SomeException here is normally an IOError which lacks
+        -- very much structure, in the future we could try to catch
+        -- a more structured exception and further refine the
+        -- displayed output. https://github.com/ndmitchell/shake/pull/812
         hPrint stderr (shakeExceptionInner _e)
     hPutStrLn stderr (esc "Build failed.")
     exitFailure