[lmi-commits] [lmi] master 97e46a92 1/4: Improve documentation

[Greg Chicares]

branch: master
commit 97e46a921842d8aab278057bb1567b3e58faa5fb
Author: Gregory W. Chicares <gchicares@sbcglobal.net>
Commit: Gregory W. Chicares <gchicares@sbcglobal.net>

    Improve documentation
    
    Revised inline documentation in light of commit ffe856cc24efed.
---
 ul_utilities.cpp | 19 +++++++++----------
 1 file changed, 9 insertions(+), 10 deletions(-)

diff --git a/ul_utilities.cpp b/ul_utilities.cpp
index b42bb136..7bc53da8 100644
--- a/ul_utilities.cpp
+++ b/ul_utilities.cpp
@@ -103,12 +103,14 @@ currency rate_times_currency
 {
     using uint64 = std::uint64_t;
 
-    // Precondition (asserted below): the premium-rate argument is
+    // Expected condition (not asserted): the premium-rate argument is
     // precise to at most eight decimals, any further digits being
-    // representation error. In practice, eight is almost universally
-    // adequate, but this is a parameter that may be adjusted if more
-    // decimals are required. The accompanying unit test gives some
-    // illustrative examples of this precondition's effect.
+    // representation error. In practice, rates are almost never
+    // rounded to more than eight digits, unless all representable
+    // digits actually are significant--e.g., in the case of a 7PP
+    // table intended to reproduce a calculation from first principles
+    // as closely as possible. This presently hardcoded parameter may
+    // require adjustment if more decimals are required.
     constexpr int radix {100'000'000};
     constexpr uint64 limit {UINT64_MAX / radix};
     static currency const cents_limit {from_cents(limit)};
@@ -143,11 +145,8 @@ currency rate_times_currency
     // implicitly asserts that values are preserved.
     uint64 irate = bourn_cast<uint64>(std::nearbyint(rate * radix));
     // If the rate really has more than eight significant digits, then
-    // perform the calculation in double precision. In practice, rates
-    // are almost never rounded to more than eight digits, unless all
-    // representable digits actually are significant--e.g., in the
-    // case of a 7PP table that strives to reproduce a calculation
-    // from first principles as closely as possible.
+    // perform the calculation in double precision. The accompanying
+    // unit test gives some illustrative examples of this conditional.
     if(!materially_equal(bourn_cast<double>(irate), rate * radix))
         {
         return rounder.c(amount * rate);