From 3d85549e79fb0861dfa87214f872f5b368d2746e Mon Sep 17 00:00:00 2001
From: Simon Michael <simon@joyful.com>
Date: Tue, 30 Dec 2025 18:47:40 -1000
Subject: [PATCH] dev:Hledger.Utils.IO: clarify expandPath, expandHomePath

---
 hledger-lib/Hledger/Utils/IO.hs | 10 ++++++----
 1 file changed, 6 insertions(+), 4 deletions(-)

diff --git a/hledger-lib/Hledger/Utils/IO.hs b/hledger-lib/Hledger/Utils/IO.hs
index 986cb4b08..1227cd719 100644
--- a/hledger-lib/Hledger/Utils/IO.hs
+++ b/hledger-lib/Hledger/Utils/IO.hs
@@ -397,8 +397,8 @@ getCurrentZonedTime = do
 getHomeSafe :: IO (Maybe FilePath)
 getHomeSafe = fmap Just getHomeDirectory `catch` (\(_ :: IOException) -> return Nothing)
 
--- | Expand a tilde (representing home directory) at the start of a file path.
--- ~username is not supported. Can raise an error.
+-- | Expand a single tilde (representing home directory) at the start of a file path.
+-- ~username is not supported. This can raise an IO error.
 expandHomePath :: FilePath -> IO FilePath
 expandHomePath = \case
     "~"          -> getHomeDirectory
@@ -409,12 +409,14 @@ expandHomePath = \case
 
 -- | Given a current directory, convert a possibly relative, possibly tilde-prefixed
 -- file path to an absolute one.
--- ~username is not supported. Leaves "-" unchanged. Can raise an error.
+-- ~username is not supported.
+-- If the file path is "-", it is left as-is.
+-- This can an raise an IO error.
 expandPath :: FilePath -> FilePath -> IO FilePath -- general type sig for use in reader parsers
 expandPath _ "-" = return "-"
 expandPath curdir p = (if isRelative p then (curdir </>) else id) <$> expandHomePath p  -- PARTIAL:
 
--- | Like expandPath, but treats the expanded path as a glob, and returns
+-- | Like @expandPath@, but treats the expanded path as a glob, and returns
 -- zero or more matched absolute file paths, alphabetically sorted.
 -- Can raise an error.
 -- For a more elaborate glob expander, see 'findMatchedFiles' (used by the include directive).