;improve valuation code docs

hledger-lib/Hledger/Reports/BalanceReport.hs

@@ -72,9 +72,9 @@ balanceReport ropts@ReportOpts{..} q j =
       dbg1 s = let p = "balanceReport" in Hledger.Utils.dbg1 (p++" "++s)  -- add prefix in debug output
 
       -- We may be converting amounts to value, according to --value-at:
-      --  transaction: convert each posting to value before summing
-      --  period:      convert totals to value at period end
-      --  date:        convert totals to value at date
+      --  transaction: value each posting at posting date before summing
+      --  period:      value totals at period end
+      --  date:        value totals at date
       mvalueat = if value_ then Just value_at_ else Nothing
       today    = fromMaybe (error' "balanceReport: ReportOpts today_ is unset so could not satisfy --value-at=now") today_
 

hledger-lib/Hledger/Reports/EntriesReport.hs

@@ -74,7 +74,8 @@ erValue ropts@ReportOpts{..} j ts = map txnvalue ts
 
         d = case value_at_ of
           AtTransaction -> postingDate p
-          AtPeriod      -> fromMaybe (postingDate p) mperiodorjournallastday
+          AtPeriod      -> fromMaybe (postingDate p)  -- XXX shouldn't happen
+                           mperiodorjournallastday
           AtNow         -> case today_ of
                              Just d  -> d
                              Nothing -> error' "erValue: ReportOpts today_ is unset so could not satisfy --value-at=now"

hledger-lib/Hledger/Reports/MultiBalanceReports.hs

@@ -132,7 +132,7 @@ multiBalanceReport ropts@ReportOpts{..} q j =
           filterJournalPostings reportq $        -- remove postings not matched by (adjusted) query
           journalSelectingAmountFromOpts ropts j
       -- One or more date spans corresponding to the report columns.
-      displayspans = dbg1 "displayspans" $ splitSpan interval_ displayspan
+      displayspans :: [DateSpan] = dbg1 "displayspans" $ splitSpan interval_ displayspan
         where
           displayspan
             | empty_    = dbg1 "displayspan (-E)" reportspan                              -- all the requested intervals
@@ -142,11 +142,24 @@ multiBalanceReport ropts@ReportOpts{..} q j =
       psPerSpan :: [([Posting], Maybe Day)] =
           dbg1 "psPerSpan"
           [(filter (isPostingInDateSpan' (whichDateFromOpts ropts) s) ps, spanEnd s) | s <- displayspans]
-      -- Check if we'll be doing valuation. Here's how it's done in the various cases:
-      --  balance -M --value-at
-      --   transaction: convert each posting to value before calculating table cell amounts (balance change or ending balance) ?
-      --   period:      convert each table cell amount (balance change or ending balance) to its value at period end
-      --   date:        convert each table cell amount to its value at date
+      -- Check if we'll be doing valuation. 
+      -- Here's the current plan for each part of the report and each --value-at:
+      --  -H starting balances:
+      --   transaction: sum of values of previous postings on their posting dates
+      --   period:      value -H starting balances at day before report start
+      --   date:        value -H starting balances at date
+      --  table cells:
+      --   transaction: value each posting before calculating table cell amounts
+      --   period:      value each table cell amount at subperiod end
+      --   date:        value each table cell amount at date
+      --  column totals:
+      --   transaction: sum/average the valued cell amounts
+      --   period:      sum/average the unvalued amounts and value at subperiod end
+      --   date:        sum/average the unvalued amounts and value at date
+      --  row totals & averages, grand total & average:
+      --   transaction: sum/average the valued amounts
+      --   period:      sum/average the unvalued amounts and value at report period end
+      --   date:        sum/average the unvalued amounts and value at date
       mvalueat = if value_ then Just value_at_ else Nothing
       today    = fromMaybe (error' "postingsReport: ReportOpts today_ is unset so could not satisfy --value-at=now") today_
       -- If --value-at=transaction is in effect, convert the postings to value before summing.

hledger-lib/Hledger/Reports/PostingsReport.hs

@@ -71,18 +71,21 @@ postingsReport ropts@ReportOpts{..} q j =
       -- postings to be included in the report, and similarly-matched postings before the report start date
       (precedingps, reportps) = matchedPostingsBeforeAndDuring ropts q j reportspan
 
-      -- We may be converting amounts to value, according to --value-at, as follows:
-      -- (keep synced with hledger_options.m4.md)
+      -- We may be converting amounts to value, according to --value-at.
+      -- Currently this is done as follows (keep synced with hledger_options.m4.md):
       --  register -M --value-at
-      --   transaction: convert each summary posting to value at posting date ; convert -H starting balance to value at day before report start
-      --   period:      convert each summary posting to value at period end   ; convert -H starting balance to value at day before report start
-      --   date:        convert each summary posting to value at date         ; convert -H starting balance to value at date
+      --   transaction: value each posting at posting date, then summarise ; value -H starting balance at day before report start
+      --   period:      value each summary posting at period end           ; value -H starting balance at day before report start
+      --   date:        value each summary posting at date                 ; value -H starting balance at date
       --  register --value-at
-      --   transaction: convert each posting to value at posting date         ; convert -H starting balance to value at day before report start
-      --   period:      convert each posting to value at report end           ; convert -H starting balance to value at day before report start
-      --   date:        convert each posting to value at date                 ; convert -H starting balance to value at date
-      --  in all cases, the running total/average is calculated from the above numbers.
-      -- "Day before report start" is a bit arbitrary.
+      --   transaction: value each posting at posting date                 ; value -H starting balance at day before report start
+      --   period:      value each posting at report end                   ; value -H starting balance at day before report start
+      --   date:        value each posting at date                         ; value -H starting balance at date
+      --
+      --  In all cases, the running total/average is calculated from the above numbers.
+      --  This might not always be what you want; to see the running total valued, try a balance report.
+      --
+      --  "Day before report start" is a bit arbitrary.
 
       mvalueat = if value_ then Just value_at_ else Nothing
       today = fromMaybe (error' "postingsReport: ReportOpts today_ is unset so could not satisfy --value-at=now") today_