From 46369b235de8d3d6520fceab6212711fd7c357cf Mon Sep 17 00:00:00 2001
From: liamzee <liam.zhu@protonmail.com>
Date: Mon, 16 Oct 2023 01:40:44 +0800
Subject: [PATCH] Add or Expand 5 Comments

To help make the Cabal codebase more accessible,
expandResponse in Cabal/Distribution.ResponseFile
received Haddock documentation.

The defaultMainHelper function in Cabal/Distribution.Simple
received hidden Haddock documentation.

In the hidden module cabal-install/Distribution.Client.Main,
the Haddock documentation for main was expanded, additional
commenting explaining the response file compatibility
code in main was added, and documentation for
mainWorker was added.
---
 Cabal/src/Distribution/Compat/ResponseFile.hs |  6 +++++
 Cabal/src/Distribution/Simple.hs              |  7 ++++++
 cabal-install/src/Distribution/Client/Main.hs | 22 +++++++++++++++++++
 3 files changed, 35 insertions(+)

diff --git a/Cabal/src/Distribution/Compat/ResponseFile.hs b/Cabal/src/Distribution/Compat/ResponseFile.hs
index c03207fed55..189a423bd08 100644
--- a/Cabal/src/Distribution/Compat/ResponseFile.hs
+++ b/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
diff --git a/Cabal/src/Distribution/Simple.hs b/Cabal/src/Distribution/Simple.hs
index d6f50d0af90..0f200922928 100644
--- a/Cabal/src/Distribution/Simple.hs
+++ b/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
diff --git a/cabal-install/src/Distribution/Client/Main.hs b/cabal-install/src/Distribution/Client/Main.hs
index 1a46893c9b8..4c9269fe271 100644
--- a/cabal-install/src/Distribution/Client/Main.hs
+++ b/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 $