move around and clean up haddock comments

AccountName.hs

@@ -46,11 +46,11 @@ s `isSubAccountNameOf` p =
 subAccountNamesFrom :: [AccountName] -> AccountName -> [AccountName]
 subAccountNamesFrom accts a = filter (`isSubAccountNameOf` a) accts
 
--- | We could almost get by with just the above, but we need smarter
+-- | We could almost get by with just the AccountName manipulations
--- structures to eg display the account tree with boring accounts elided.
+-- above, but we need smarter structures to eg display the account
--- first, here is a tree of AccountNames; Account and Account tree are
+-- tree with boring accounts elided.  This converts a list of
--- defined later.
+-- AccountNames to a tree (later we will convert that to a tree of
-
+-- Accounts.)
 accountNameTreeFrom_props =
     [
      accountNameTreeFrom ["a"]       == Node "top" [Node "a" []],

Amount.hs

@@ -1,6 +1,7 @@
 {-|
-a simple amount is a currency, quantity pair:
+A simple amount is a currency, quantity pair:
 
+@
   $1 
   £-50
   EUR 3.44 
@@ -8,18 +9,20 @@ a simple amount is a currency, quantity pair:
   1.5h
   90m
   0 
+@
 
-a mixed amount is one or more simple amounts:
+A mixed amount is one or more simple amounts:
 
+@
   $50, EUR 3, AAPL 500
   16h, $13.55, oranges 6
+@
 
-currencies may be convertible or not (eg, currencies representing
+Currencies may be convertible or not (eg, currencies representing
 non-money commodities). A mixed amount containing only convertible
-currencies can be converted to a simple amount.
+currencies can be converted to a simple amount. Arithmetic examples:
-
-arithmetic:
 
+@
   $1 - $5 = $-4
   $1 + EUR 0.76 = $2
   EUR0.76 + $1 = EUR 1.52
@@ -28,7 +31,7 @@ arithmetic:
   ($50, EUR 3, AAPL 500) + ($13.55, oranges 6) = $67.51, AAPL 500, oranges 6
   ($50, EUR 3) * $-1 = $-53.96
   ($50, AAPL 500) * $-1 = error
-   
+@   
 -}
 
 module Amount
@@ -80,7 +83,7 @@ instance Num Amount where
     (-) = amountop (-)
     (*) = amountop (*)
 
--- | problem: when an integer is converted to an amount it must pick a
+-- problem: when an integer is converted to an amount it must pick a
 -- precision, which we specify here (should be infinite ?). This can
 -- affect amount arithmetic, in particular the sum of a list of amounts.
 -- So, we may need to adjust the precision after summing amounts.

Ledger.hs

@@ -110,74 +110,86 @@ ledgerAccountTree l depth =
 addDataToAccountNameTree :: Ledger -> Tree AccountName -> Tree Account
 addDataToAccountNameTree = treemap . ledgerAccount
 
--- | balance report support
---
--- examples: here is a sample account tree:
---
--- assets
---  cash
---  checking
---  saving
--- equity
--- expenses
---  food
---  shelter
--- income
---  salary
--- liabilities
---  debts
---
--- standard balance command shows all top-level accounts:
---
--- > ledger bal
---
---  $ assets      
---  $ equity
---  $ expenses    
---  $ income      
---  $ liabilities 
---
--- with an account pattern, show only the ones with matching names:
---
--- > ledger bal asset
---
---  $ assets      
---
--- with -s, show all subaccounts of matched accounts:
---
--- > ledger -s bal asset
---
---  $ assets      
---  $  cash       
---  $  checking   
---  $  saving
---
--- we elide boring accounts in two ways:
---
--- - leaf accounts and branches with 0 balance or 0 transactions are omitted
---
--- - inner accounts with 0 transactions and 1 subaccount are displayed inline
---
--- so this:
---
--- a (0 txns)
---   b (0 txns)
---     c
---       d
--- e (0 txns)
---   f
---   g
--- h (0 txns)
---   i (0 balance)
---
--- is displayed like:
---
--- a:b:c
---   d
--- e
---   f
---   g
 
+{-| 
+This and the functions below help generate ledger-compatible balance
+reports. Here's how it should work:
+
+a sample account tree:
+
+@
+assets
+ cash
+ checking
+ saving
+equity
+expenses
+ food
+ shelter
+income
+ salary
+liabilities
+ debts
+@
+
+the standard balance command shows all top-level accounts:
+
+@
+\> ledger balance
+$ assets      
+$ equity
+$ expenses    
+$ income      
+$ liabilities 
+@
+
+with an account pattern, show only the ones with matching names:
+
+@
+\> ledger balance asset
+$ assets      
+@
+
+with -s, show all subaccounts of matched accounts:
+
+@
+\> ledger -s balance asset
+$ assets      
+$  cash       
+$  checking   
+$  saving
+@
+
+we elide boring accounts in two ways:
+
+- leaf accounts and branches with 0 balance or 0 transactions are omitted
+
+- inner accounts with 0 transactions and 1 subaccount are displayed inline
+
+so this:
+
+@
+a (0 txns)
+  b (0 txns)
+    c
+      d
+e (0 txns)
+  f
+  g
+h (0 txns)
+  i (0 balance)
+@
+
+is displayed like:
+
+@
+a:b:c
+  d
+e
+  f
+  g
+@
+-}
 showLedgerAccounts :: Ledger -> Int -> String
 showLedgerAccounts l maxdepth = 
     concatMap 

LedgerEntry.hs

@@ -8,18 +8,23 @@ import Amount
 
 instance Show LedgerEntry where show = showEntryDescription
 
--- | for register report
+{-
---
+Helpers for the register report. A register entry is displayed as two
--- a register entry is displayed as two or more lines like this:
+or more lines like this:
--- date       description          account                 amount       balance
+
--- DDDDDDDDDD dddddddddddddddddddd aaaaaaaaaaaaaaaaaaaaaa  AAAAAAAAAAA AAAAAAAAAAAA
+@
---                                 aaaaaaaaaaaaaaaaaaaaaa  AAAAAAAAAAA AAAAAAAAAAAA
+date       description          account                 amount       balance
---                                 ...                     ...         ...
+DDDDDDDDDD dddddddddddddddddddd aaaaaaaaaaaaaaaaaaaaaa  AAAAAAAAAAA AAAAAAAAAAAA
--- datewidth = 10
+                                aaaaaaaaaaaaaaaaaaaaaa  AAAAAAAAAAA AAAAAAAAAAAA
--- descwidth = 20
+                                ...                     ...         ...
--- acctwidth = 22
+
--- amtwidth  = 11
+datewidth = 10
--- balwidth  = 12
+descwidth = 20
+acctwidth = 22
+amtwidth  = 11
+balwidth  = 12
+@
+-}
 
 showEntryDescription e = (showDate $ edate e) ++ " " ++ (showDescription $ edescription e) ++ " "
 showDate d = printf "%-10s" d
@@ -36,18 +41,22 @@ autofillEntry e@(LedgerEntry _ _ _ _ _ ts _) =
       True -> e'
       False -> (error $ "transactions don't balance in " ++ show e)
 
--- | the print command shows cleaned up ledger file entries, something like:
+{-|
---
+Helper for the print command which shows cleaned up ledger file
--- yyyy/mm/dd[ *][ CODE] description.........          [  ; comment...............]
+entries, something like:
---     account name 1.....................  ...$amount1[  ; comment...............]
---     account name 2.....................  ..$-amount1[  ; comment...............]
---
--- pcodewidth    = no limit -- 10
--- pdescwidth    = no limit -- 20
--- pacctwidth    = 35 minimum, no maximum
--- pamtwidth     = 11
--- pcommentwidth = no limit -- 22
 
+@
+yyyy/mm/dd[ *][ CODE] description.........          [  ; comment...............]
+    account name 1.....................  ...$amount1[  ; comment...............]
+    account name 2.....................  ..$-amount1[  ; comment...............]
+
+pcodewidth    = no limit -- 10
+pdescwidth    = no limit -- 20
+pacctwidth    = 35 minimum, no maximum
+pamtwidth     = 11
+pcommentwidth = no limit -- 22
+@
+-}
 showEntry :: LedgerEntry -> String
 showEntry e = 
     unlines $ [precedingcomment ++ description] ++ (showtxns $ etransactions e) ++ [""]

Types.hs

@@ -1,35 +1,11 @@
+{-| 
+All the basic data types, defined here for easy re-use. See "Main".
+-}
 module Types 
 where
 import Utils
 import qualified Data.Map as Map
 
-{-
-Here is the approximate module hierarchy. The early code defined types in
-each module and so was strictly layered. Now, all data types have been
-moved to the bottom. The modules are still used to group related
-functions/methods (" make overview " to list those).
-
-hledger
- Options
- Tests
-  Parse
-   Models
-    TimeLog
-     TimeLogEntry
-    Ledger
-     Account
-      Transaction
-     LedgerFile
-      LedgerEntry
-       LedgerTransaction
-        AccountName
-        Amount
-         Currency
-          Types
-           Utils
-
--}
-
 -- | account and description-matching patterns
 type FilterPatterns = (Maybe Regex, Maybe Regex)
                        
@@ -42,14 +18,14 @@ data Currency = Currency {
       rate :: Double -- relative to the dollar.. 0 rates not supported yet
     } deriving (Eq,Show)
 
--- | some amount of money, time, stock, oranges, etc.
+-- | some amount of money, time, stock, oranges, or whatever.
 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
+-- | AccountNames are strings like assets:cash:petty, from which we derive
 -- the chart of accounts
 type AccountName = String
 
@@ -60,7 +36,7 @@ data LedgerTransaction = LedgerTransaction {
       tcomment :: String
     } deriving (Eq)
 
--- | a ledger entry, with two or more balanced transactions
+-- | a ledger entry, containing two or more balanced transactions
 data LedgerEntry = LedgerEntry {
       edate :: Date,
       estatus :: Bool,
@@ -83,13 +59,14 @@ data PeriodicEntry = PeriodicEntry {
       p_transactions :: [LedgerTransaction]
     } deriving (Eq)
 
--- | we also parse timeclock.el timelogs
+-- | a timelog entry (we also parse timeclock.el timelogs)
 data TimeLogEntry = TimeLogEntry {
       tlcode :: Char,
       tldatetime :: DateTime,
       tlcomment :: String
     } deriving (Eq,Ord)
 
+-- | a parsed timelog file
 data TimeLog = TimeLog {
       timelog_entries :: [TimeLogEntry]
     } deriving (Eq)
@@ -114,9 +91,9 @@ data Transaction = Transaction {
 
 -- | cached information for a particular account
 data Account = Account {
-      aname :: AccountName, 
+      aname :: AccountName,           -- ^ the account name
-      atransactions :: [Transaction], -- ^ excludes sub-accounts
+      atransactions :: [Transaction], -- ^ the transactions, excluding sub-accounts
-      abalance :: Amount              -- ^ includes sub-accounts
+      abalance :: Amount              -- ^ the total balance, including sub-accounts
     }
 
 -- | a ledger with account information cached for faster queries

hledger.hs

@@ -6,11 +6,37 @@ Copyright (c) 2007-2008 Simon Michael <simon@joyful.com>
 Released under GPL version 3 or later.
 
 This is a minimal haskell clone of John Wiegley's ledger
-<http://newartisans.com/software/ledger.html>.  hledger does basic
+<http://newartisans.com/software/ledger.html>.  hledger generates
-register & balance reports, and demonstrates a (naive) purely
+simple ledger-compatible register & balance reports from a standard
-functional implementation of ledger.
+ledger file, and demonstrates a (naive) purely functional
+implementation of ledger.
 
-See the "Types" module for a code overview.
+Code overview: 
+
+The early code defined types in each module and so was very strictly
+layered. Since then, all data types have been moved to "Types" at the
+bottom, but the original modules are still used to group related
+functions/methods. Here is the approximate module hierarchy:
+
+@
+hledger ("Main")
+ "Options"
+ "Tests"
+  "Parse"
+   "Models"
+    "TimeLog"
+    "Ledger"
+     "Account"
+      "Transaction"
+     "LedgerFile"
+      "LedgerEntry"
+       "LedgerTransaction"
+        "AccountName"
+        "Amount"
+         "Currency"
+          "Types"
+           "Utils"
+@
 -}
 
 module Main