clarify Types

Types.hs

@@ -6,34 +6,49 @@ where
 import Utils
 import qualified Data.Map as Map
 
+-- | a date
 type Date = String
 
+-- | a date and time
 type DateTime = String
 
+-- | the currency of an Amount. Rates are currently hardcoded.
 data Currency = Currency {
       symbol :: String,
-      rate :: Double -- relative to the dollar.. 0 rates not supported yet
+      rate :: Double -- ^ relative to the dollar.. 0 rates not supported yet
     } deriving (Eq,Show)
 
--- | some amount of money, time, stock, oranges, or whatever.
+-- | some amount of money, shares, or anything else.
 data Amount = Amount {
       currency :: Currency,
       quantity :: Double,
-      precision :: Int -- number of significant decimal places
+      precision :: Int           -- ^ number of significant decimal places
     } deriving (Eq)
 
 -- | AccountNames are strings like assets:cash:petty, from which we derive
 -- the chart of accounts
 type AccountName = String
 
--- | a line item in a ledger entry
+-- | a transaction line within a ledger entry.
 data LedgerTransaction = LedgerTransaction {
       taccount :: AccountName,
       tamount :: Amount,
       tcomment :: String
     } deriving (Eq)
 
--- | a ledger entry, containing two or more balanced transactions
+-- | a ledger "modifier" entry. Currently ignored.
+data ModifierEntry = ModifierEntry {
+      valueexpr :: String,
+      m_transactions :: [LedgerTransaction]
+    } deriving (Eq)
+
+-- | a ledger "periodic" entry. Currently ignored.
+data PeriodicEntry = PeriodicEntry {
+      periodexpr :: String,
+      p_transactions :: [LedgerTransaction]
+    } deriving (Eq)
+
+-- | a regular ledger entry, containing two or more transactions which balance
 data LedgerEntry = LedgerEntry {
       edate :: Date,
       estatus :: Bool,
@@ -44,19 +59,16 @@ data LedgerEntry = LedgerEntry {
       epreceding_comment_lines :: String
     } deriving (Eq)
 
--- | an automated ledger entry
-data ModifierEntry = ModifierEntry {
-      valueexpr :: String,
-      m_transactions :: [LedgerTransaction]
+-- | a parsed ledger file. We call it raw to distinguish from the cached
+-- version below.
+data RawLedger = RawLedger {
+      modifier_entries :: [ModifierEntry],
+      periodic_entries :: [PeriodicEntry],
+      entries :: [LedgerEntry],
+      final_comment_lines :: String
     } deriving (Eq)
 
--- | a periodic ledger entry
-data PeriodicEntry = PeriodicEntry {
-      periodexpr :: String,
-      p_transactions :: [LedgerTransaction]
-    } deriving (Eq)
-
--- | a timelog entry (we also parse timeclock.el timelogs)
+-- | a timelog entry in a timelog file (generated by timeclock.el)
 data TimeLogEntry = TimeLogEntry {
       tlcode :: Char,
       tldatetime :: DateTime,
@@ -68,16 +80,9 @@ data TimeLog = TimeLog {
       timelog_entries :: [TimeLogEntry]
     } deriving (Eq)
 
--- | a parsed ledger file
-data RawLedger = RawLedger {
-      modifier_entries :: [ModifierEntry],
-      periodic_entries :: [PeriodicEntry],
-      entries :: [LedgerEntry],
-      final_comment_lines :: String
-    } deriving (Eq)
-
--- | we flatten LedgerEntries and LedgerTransactions into Transactions,
--- which are simpler to query at the cost of some data duplication
+-- | optimisations: these types provide some caching and are easier to work with.
+-- A Transaction is a LedgerTransaction with some of its parent
+-- LedgerEntry's data attached.
 data Transaction = Transaction {
       entryno :: Int,
       date :: Date,
@@ -86,14 +91,16 @@ data Transaction = Transaction {
       amount :: Amount
     } deriving (Eq)
 
--- | cached information for a particular account
+-- | an Account stores an account name, all transactions in the account
+-- (excluding subaccounts), and the total balance (including subaccounts).
 data Account = Account {
-      aname :: AccountName,           -- ^ the account name
-      atransactions :: [Transaction], -- ^ the transactions, excluding sub-accounts
-      abalance :: Amount              -- ^ the total balance, including sub-accounts
+      aname :: AccountName,
+      atransactions :: [Transaction],
+      abalance :: Amount
     }
 
--- | a ledger with account information cached for faster queries
+-- | a raw ledger plus its tree of account names, a map from account names
+-- to Accounts, and the preferred precision.
 data Ledger = Ledger {
       rawledger :: RawLedger,
       accountnametree :: Tree AccountName,