From 1ef777a1b8017271c2f209e2404697f0f3048786 Mon Sep 17 00:00:00 2001
From: Simon Michael <simon@joyful.com>
Date: Fri, 3 Apr 2009 20:55:49 +0000
Subject: [PATCH] improve type docs

---
 Ledger/Account.hs     |  9 +++++---
 Ledger/Ledger.hs      | 12 ++++++----
 Ledger/Transaction.hs |  6 +++--
 Ledger/Types.hs       | 52 ++++++++++++++++++++-----------------------
 4 files changed, 42 insertions(+), 37 deletions(-)

diff --git a/Ledger/Account.hs b/Ledger/Account.hs
index d71ae47cd..8451150cc 100644
--- a/Ledger/Account.hs
+++ b/Ledger/Account.hs
@@ -1,8 +1,11 @@
 {-|
 
-An 'Account' stores, for efficiency: an 'AccountName', all transactions in
-the account (excluding subaccounts), and the account balance (including
-subaccounts).
+A compound data type for efficiency. An 'Account' stores
+
+- an 'AccountName',
+- all `Transaction`s (postings plus ledger transaction info) in the
+  account, excluding subaccounts
+- and the account balance, including subaccounts.
 
 -}
 
diff --git a/Ledger/Ledger.hs b/Ledger/Ledger.hs
index 061700c90..1ec96dcd7 100644
--- a/Ledger/Ledger.hs
+++ b/Ledger/Ledger.hs
@@ -1,9 +1,13 @@
 {-|
 
-A 'Ledger' stores, for efficiency, a 'RawLedger' plus its tree of account
-names, and a map from account names to 'Account's. It may also have had
-uninteresting 'LedgerTransaction's and 'Posting's filtered out. It also stores
-the complete ledger file text for the ui command.
+A compound data type for efficiency. A 'Ledger' caches information derived
+from a 'RawLedger' so that it is easy to query. It typically has had
+uninteresting 'LedgerTransaction's and 'Posting's removed. It contains
+
+- the original 'RawLedger'
+- a tree of account names
+- a map from account names to 'Account's
+- the full text of the journal file, when available
 
 -}
 
diff --git a/Ledger/Transaction.hs b/Ledger/Transaction.hs
index e4abf5c9f..33672e1b2 100644
--- a/Ledger/Transaction.hs
+++ b/Ledger/Transaction.hs
@@ -1,7 +1,9 @@
 {-|
 
-A 'Transaction' is a 'Posting' with its parent 'LedgerTransaction' \'s date and
-description attached. These are what we actually query when doing reports.
+A compound data type for efficiency. A 'Transaction' is a 'Posting' with
+its parent 'LedgerTransaction' \'s date and description attached. These
+are what we mostly work with when doing reports, and this name is pretty
+ingrained.
 
 -}
 
diff --git a/Ledger/Types.hs b/Ledger/Types.hs
index a271754c3..96733d5d1 100644
--- a/Ledger/Types.hs
+++ b/Ledger/Types.hs
@@ -1,25 +1,23 @@
 {-|
 
-This is the next layer up from Ledger.Utils. All main data types are
-defined here to avoid import cycles; see the corresponding modules for
-documentation.
+Most data types are defined here to avoid import cycles. See the
+corresponding modules for each type's documentation.
 
-On the current use of terminology:
+A note about entry/transaction/posting terminology:
 
-- ledger 2 has Entrys containing Transactions.
-
-- hledger 0.4 has Entrys containing RawTransactions, and Transactions
-  which are a RawTransaction with its parent Entry's info added.
-  Transactions are what we most work with when reporting and are
-  ubiquitous in the code and docs.
-
-- ledger 3 has Transactions containing Postings.
-
-- hledger 0.5 has LedgerTransactions containing Postings, with
-  Transactions kept just as in hledger 0.4 (a Posting with it's parent's
-  info added). They could be named PartialTransactions or
-  TransactionPostings, but that just gets too verbose and obscure for devs
-  and users.
+  - ledger 2 had Entrys containing Transactions.
+  
+  - hledger 0.4 had Entrys containing RawTransactions, and Transactions
+    which are a RawTransaction with its parent Entry's info added.
+    Transactions are what we most work with when reporting and are
+    ubiquitous in the code and docs.
+  
+  - ledger 3 has Transactions containing Postings.
+  
+  - hledger 0.5 has LedgerTransactions containing Postings, with
+    Transactions kept as before (a Posting plus it's parent's info).
+    These could be named PartialTransactions or TransactionPostings, but
+    it gets too verbose and obscure for devs and users.
 
 -}
 
@@ -113,22 +111,20 @@ data RawLedger = RawLedger {
       filepath :: FilePath
     } deriving (Eq)
 
--- compound types for efficiency
-
 data Transaction = Transaction {
       tnum :: Int,
-      status :: Bool,
-      date :: Day,
-      description :: String,
-      account :: AccountName,
-      amount :: MixedAmount,
-      ttype :: PostingType
+      status :: Bool,            -- ^ posting status
+      date :: Day,               -- ^ ledger transaction date
+      description :: String,     -- ^ ledger transaction description
+      account :: AccountName,    -- ^ posting account
+      amount :: MixedAmount,     -- ^ posting amount
+      ttype :: PostingType       -- ^ posting type
     } deriving (Eq)
 
 data Account = Account {
       aname :: AccountName,
-      atransactions :: [Transaction],
-      abalance :: MixedAmount
+      atransactions :: [Transaction], -- ^ transactions in this account
+      abalance :: MixedAmount         -- ^ sum of transactions in this account and subaccounts
     }
 
 data Ledger = Ledger {