From 9327025cfd4bb3cbfcfefc83451d8c5f6b3df6a0 Mon Sep 17 00:00:00 2001
From: Phil de Joux <philderbeast@gmail.com>
Date: Tue, 12 Dec 2023 15:06:15 -0500
Subject: [PATCH] Add symlink haddocks

As requested in review
---
 cabal-install/src/Distribution/Client/CmdInstall.hs    |  2 ++
 .../src/Distribution/Client/InstallSymlink.hs          | 10 +++++++++-
 2 files changed, 11 insertions(+), 1 deletion(-)

diff --git a/cabal-install/src/Distribution/Client/CmdInstall.hs b/cabal-install/src/Distribution/Client/CmdInstall.hs
index 07db85cbeaf..462e980d0a2 100644
--- a/cabal-install/src/Distribution/Client/CmdInstall.hs
+++ b/cabal-install/src/Distribution/Client/CmdInstall.hs
@@ -1004,6 +1004,8 @@ disableTestsBenchsByDefault configFlags =
     , configBenchmarks = Flag False <> configBenchmarks configFlags
     }
 
+-- | Prepares a record containing the information needed to either symlink or
+-- copy an executable.
 symlink :: OverwritePolicy -> InstallExe -> UnitId -> UnqualComponentName -> Symlink
 symlink
   overwritePolicy
diff --git a/cabal-install/src/Distribution/Client/InstallSymlink.hs b/cabal-install/src/Distribution/Client/InstallSymlink.hs
index 8025153531a..9dc19fb3750 100644
--- a/cabal-install/src/Distribution/Client/InstallSymlink.hs
+++ b/cabal-install/src/Distribution/Client/InstallSymlink.hs
@@ -252,6 +252,8 @@ symlinkBinaries
       cinfo = compilerInfo comp
       (CompilerId compilerFlavor _) = compilerInfoId cinfo
 
+-- | A record needed to either check if a symlink is possible or to create a
+-- symlink. Also used if copying instead of symlinking.
 data Symlink = Symlink
   { overwritePolicy :: OverwritePolicy
   -- ^ Whether to force overwrite an existing file.
@@ -265,7 +267,12 @@ data Symlink = Symlink
   -- ^ The name of the executable to in the private bin dir, eg @foo-1.0@.
   }
 
--- | How to handle symlinking a binary.
+-- | After checking if a target is writeable given the overwrite policy,
+-- dispatch to an appropriate action;
+--  * @onMissing@ if the target doesn't exist
+--  * @onOverwrite@ if the target exists and we are allowed to overwrite it
+--  * @onNever@ if the target exists and we are never allowed to overwrite it
+--  * @onPrompt@ if the target exists and we are allowed to overwrite after propmpting
 onSymlinkBinary
   :: IO a
   -- ^ Missing action
@@ -274,6 +281,7 @@ onSymlinkBinary
   -> IO a
   -- ^ Never action
   -> IO a
+  -- ^ Prompt action
   -> Symlink
   -> IO a
 onSymlinkBinary