Added or expanded 5 comments…

Cabal/src/Distribution/Compat/ResponseFile.hs

@@ -65,6 +65,12 @@ escape cs c
 
 #endif
 
+-- | The arg file / response file parser.
+--
+-- This is not a well-documented capability, and is a bit eccentric
+-- (try @cabal \@foo \@bar@ to see what that does), but is crucial
+-- for allowing complex arguments to cabal and cabal-install when
+-- using command prompts with strongly-limited argument length.
 expandResponse :: [String] -> IO [String]
 expandResponse = go recursionLimit "."
   where

Cabal/src/Distribution/Simple.hs

@@ -155,6 +155,13 @@ defaultMainWithHooksNoReadArgs :: UserHooks -> GenericPackageDescription -> [Str
 defaultMainWithHooksNoReadArgs hooks pkg_descr =
   defaultMainHelper hooks{readDesc = return (Just pkg_descr)}
 
+-- | Less the helper, and more the central command chooser of
+-- the Simple build system, with other defaultMain functions acting as
+-- exposed callers.
+--
+-- Given hooks and args, this runs 'commandsRun' onto the args,
+-- getting 'CommandParse' data back, which is then pattern-matched into
+-- IO actions for execution.
 defaultMainHelper :: UserHooks -> Args -> IO ()
 defaultMainHelper hooks args = topHandler $ do
   args' <- expandResponse args

cabal-install/src/Distribution/Client/Main.hs

@@ -267,6 +267,18 @@ import System.IO
   )
 
 -- | Entry point
+--
+-- This does three things.
+--
+-- One, it initializes the program, providing support for termination
+-- signals, preparing console linebuffering, and relaxing encoding errors.
+--
+-- Two, it processes (via an IO action) response
+-- files, calling expandResponse in Cabal/Distribution.Compat.ResponseFile
+--
+-- Three, it calls the mainWorker, which calls the argument parser,
+-- producing CommandParse data, which mainWorker pattern-matches
+-- into IO actions for execution.
 main :: [String] -> IO ()
 main args = do
   installTerminationHandler
@@ -279,6 +291,11 @@ main args = do
   -- when writing to stderr and stdout.
   relaxEncodingErrors stdout
   relaxEncodingErrors stderr
+
+  -- Response files support.
+  -- See expandResponse documentation in
+  -- Cabal/Distribution.Compat.ResponseFile
+  -- for more information.
   let (args0, args1) = break (== "--") args
 
   mainWorker =<< (++ args1) <$> expandResponse args0
@@ -296,6 +313,11 @@ warnIfAssertionsAreEnabled =
     assertionsEnabledMsg =
       "Warning: this is a debug build of cabal-install with assertions enabled."
 
+-- | Core worker, similar to defaultMainHelper in Cabal/Distribution.Simple
+--
+-- With an exception-handler @topHandler@, mainWorker calls commandsRun
+-- to parse arguments, then pattern-matches the CommandParse data
+-- into IO actions for execution.
 mainWorker :: [String] -> IO ()
 mainWorker args = do
   topHandler $