improve type docs

Ledger/Account.hs

@@ -1,8 +1,11 @@
 {-|
 
-An 'Account' stores, for efficiency: an 'AccountName', all transactions in
+A compound data type for efficiency. An 'Account' stores
-the account (excluding subaccounts), and the account balance (including
+
-subaccounts).
+- an 'AccountName',
+- all `Transaction`s (postings plus ledger transaction info) in the
+  account, excluding subaccounts
+- and the account balance, including subaccounts.
 
 -}
 

Ledger/Ledger.hs

@@ -1,9 +1,13 @@
 {-|
 
-A 'Ledger' stores, for efficiency, a 'RawLedger' plus its tree of account
+A compound data type for efficiency. A 'Ledger' caches information derived
-names, and a map from account names to 'Account's. It may also have had
+from a 'RawLedger' so that it is easy to query. It typically has had
-uninteresting 'LedgerTransaction's and 'Posting's filtered out. It also stores
+uninteresting 'LedgerTransaction's and 'Posting's removed. It contains
-the complete ledger file text for the ui command.
+
+- 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
 
 -}
 

Ledger/Transaction.hs

@@ -1,7 +1,9 @@
 {-|
 
-A 'Transaction' is a 'Posting' with its parent 'LedgerTransaction' \'s date and
+A compound data type for efficiency. A 'Transaction' is a 'Posting' with
-description attached. These are what we actually query when doing reports.
+its parent 'LedgerTransaction' \'s date and description attached. These
+are what we mostly work with when doing reports, and this name is pretty
+ingrained.
 
 -}
 

Ledger/Types.hs

@@ -1,25 +1,23 @@
 {-|
 
-This is the next layer up from Ledger.Utils. All main data types are
+Most data types are defined here to avoid import cycles. See the
-defined here to avoid import cycles; see the corresponding modules for
+corresponding modules for each type's documentation.
-documentation.
 
-On the current use of terminology:
+A note about entry/transaction/posting terminology:
 
-- ledger 2 has Entrys containing Transactions.
+  - ledger 2 had Entrys containing Transactions.
   
-- hledger 0.4 has Entrys containing RawTransactions, and Transactions
+  - hledger 0.4 had Entrys containing RawTransactions, and Transactions
-  which are a RawTransaction with its parent Entry's info added.
+    which are a RawTransaction with its parent Entry's info added.
-  Transactions are what we most work with when reporting and are
+    Transactions are what we most work with when reporting and are
-  ubiquitous in the code and docs.
+    ubiquitous in the code and docs.
   
-- ledger 3 has Transactions containing Postings.
+  - ledger 3 has Transactions containing Postings.
   
-- hledger 0.5 has LedgerTransactions containing Postings, with
+  - hledger 0.5 has LedgerTransactions containing Postings, with
-  Transactions kept just as in hledger 0.4 (a Posting with it's parent's
+    Transactions kept as before (a Posting plus it's parent's info).
-  info added). They could be named PartialTransactions or
+    These could be named PartialTransactions or TransactionPostings, but
-  TransactionPostings, but that just gets too verbose and obscure for devs
+    it gets too verbose and obscure for devs and users.
-  and users.
 
 -}
 
@@ -113,22 +111,20 @@ data RawLedger = RawLedger {
       filepath :: FilePath
     } deriving (Eq)
 
--- compound types for efficiency
-
 data Transaction = Transaction {
       tnum :: Int,
-      status :: Bool,
+      status :: Bool,            -- ^ posting status
-      date :: Day,
+      date :: Day,               -- ^ ledger transaction date
-      description :: String,
+      description :: String,     -- ^ ledger transaction description
-      account :: AccountName,
+      account :: AccountName,    -- ^ posting account
-      amount :: MixedAmount,
+      amount :: MixedAmount,     -- ^ posting amount
-      ttype :: PostingType
+      ttype :: PostingType       -- ^ posting type
     } deriving (Eq)
 
 data Account = Account {
       aname :: AccountName,
-      atransactions :: [Transaction],
+      atransactions :: [Transaction], -- ^ transactions in this account
-      abalance :: MixedAmount
+      abalance :: MixedAmount         -- ^ sum of transactions in this account and subaccounts
     }
 
 data Ledger = Ledger {