From c48c41bcd2c8ff01e3aace1931344c248ef08fdc Mon Sep 17 00:00:00 2001
From: Simon Michael <simon@joyful.com>
Date: Fri, 18 Jul 2025 07:17:30 -0700
Subject: [PATCH] dev:timeclock: cleanups

---
 hledger-lib/Hledger/Data/Timeclock.hs       | 22 ++++++++++++---------
 hledger-lib/Hledger/Read/TimeclockReader.hs |  4 ++--
 2 files changed, 15 insertions(+), 11 deletions(-)

diff --git a/hledger-lib/Hledger/Data/Timeclock.hs b/hledger-lib/Hledger/Data/Timeclock.hs
index ad1f76a37..c7f13c67f 100644
--- a/hledger-lib/Hledger/Data/Timeclock.hs
+++ b/hledger-lib/Hledger/Data/Timeclock.hs
@@ -59,7 +59,7 @@ data Sessions = Sessions
       active :: [TimeclockEntry]
     }
 
--- Find the relevant clockin in the actives list that should be paired with this clockout.
+-- | Find the relevant clockin in the actives list that should be paired with this clockout.
 -- If there is a session that has the same account name, then use that.
 -- Otherwise, if there is an active anonymous session, use that.
 -- Otherwise, raise an error.
@@ -81,11 +81,11 @@ findInForOut o ([], activeins) =
               (l ++ " | " ++ show o)
               (replicate (length l) ' ' ++ " |" ++ replicate c ' ' ++ "^")
 
--- Assuming that entries has been sorted, we go through each time log entry.
+-- | Assuming that entries have been sorted, we go through each time log entry.
 -- We collect all of the "i" in the list "actives," and each time we encounter
 -- an "o," we look for the corresponding "i" in actives.
 -- If we cannot find it, then it is an error (since the list is sorted).
--- If the "o" is recorded on a different day than the "i," then we close the
+-- If the "o" is recorded on a different day than the "i" then we close the
 -- active entry at the end of its day, replace it in the active list
 -- with a start at midnight on the next day, and try again.
 -- This raises an error if any outs cannot be paired with an in.
@@ -118,10 +118,11 @@ pairClockEntries (entry : rest) actives sessions
                   (tlaccount entry)
             else entry : actives
 
--- | Convert time log entries to journal transactions. When there is no
--- clockout, add one with the provided current time. Sessions crossing
--- midnight are split into days to give accurate per-day totals.
--- If any entries cannot be paired as expected, then an error is raised.
+-- | Convert time log entries to journal transactions, allowing multiple clocked-in sessions at once.
+-- When there is no clockout, one is added with the provided current time.
+-- Sessions crossing midnight are split into days to give accurate per-day totals.
+-- If any entries cannot be paired as expected, an error is raised.
+-- This is the default behaviour.
 timeclockEntriesToTransactions :: LocalTime -> [TimeclockEntry] -> [Transaction]
 timeclockEntriesToTransactions now entries = transactions
   where
@@ -134,9 +135,12 @@ timeclockEntriesToTransactions now entries = transactions
     stillopen = pairClockEntries ((active sessions) <> outs) [] []
     transactions = map transactionsFromSession $ sortBy (\s1 s2 -> compare (in' s1) (in' s2)) (completed sessions ++ completed stillopen)
 
--- | Convert time log entries to journal transactions, expecting the entries to be
--- a strict in/out cycle. When there is no clockout, add one with the provided current time. 
+-- | Convert time log entries to journal transactions, allowing only one clocked-in session at a time.
+-- Entries must be a strict alternation of in and out, beginning with in.
+-- When there is no clockout, one is added with the provided current time. 
 -- Sessions crossing midnight are split into days to give accurate per-day totals.
+-- If entries are not in the expected in/out order, an error is raised.
+-- This is the legacy behaviour, enabled by --old-timeclock.
 timeclockEntriesToTransactionsSingle :: LocalTime -> [TimeclockEntry] -> [Transaction]
 timeclockEntriesToTransactionsSingle _ [] = []
 timeclockEntriesToTransactionsSingle now [i]
diff --git a/hledger-lib/Hledger/Read/TimeclockReader.hs b/hledger-lib/Hledger/Read/TimeclockReader.hs
index ad953219e..750e47a96 100644
--- a/hledger-lib/Hledger/Read/TimeclockReader.hs
+++ b/hledger-lib/Hledger/Read/TimeclockReader.hs
@@ -106,13 +106,13 @@ timeclockfilep iopts = do many timeclockitemp
                           -- but it simplifies code above.
                           now <- liftIO getCurrentLocalTime
                           -- journalFinalise expects the transactions in reverse order, so reverse the output in either case
-                          let j' = if (_oldtimeclock iopts) then 
+                          let j' = if _oldtimeclock iopts then 
                                 -- timeclockEntriesToTransactionsSingle expects the entries to be in normal order, 
                                 -- but they have been parsed in reverse order, so reverse them before calling
                                 j{jtxns = reverse $ timeclockEntriesToTransactionsSingle now $ reverse es, jparsetimeclockentries = []}
                               else 
                                 -- We don't need to reverse these transactions 
-                                -- since they are sorted inside of timeclockEntiresToTransactions
+                                -- since they are sorted inside of timeclockEntriesToTransactions
                                 j{jtxns = reverse $ timeclockEntriesToTransactions now es, jparsetimeclockentries = []}
                           return j'
     where