[lmi-commits] [5685] Rearrange and improve documentation

[Greg Chicares]

Revision: 5685
          http://svn.sv.gnu.org/viewvc/?view=rev&root=lmi&revision=5685
Author:   chicares
Date:     2013-04-16 12:15:24 +0000 (Tue, 16 Apr 2013)
Log Message:
-----------
Rearrange and improve documentation

Modified Paths:
--------------
    lmi/trunk/ChangeLog
    lmi/trunk/premium_tax.cpp
    lmi/trunk/premium_tax.hpp

Modified: lmi/trunk/ChangeLog
===================================================================
--- lmi/trunk/ChangeLog 2013-04-16 12:14:18 UTC (rev 5684)
+++ lmi/trunk/ChangeLog 2013-04-16 12:15:24 UTC (rev 5685)
@@ -32002,3 +32002,19 @@
   toolbar.xrc
 Add a "Print case to disk" toolbar button.
 
+20130416T1213Z <address@hidden> [543]
+
+  dbdict.hpp
+Improve documentation.
+
+20130416T1214Z <address@hidden> [544]
+
+  premium_tax_test.cpp
+Test premium-tax rates.
+
+20130416T1215Z <address@hidden> [544]
+
+  premium_tax.cpp
+  premium_tax.hpp
+Rearrange and improve documentation.
+

Modified: lmi/trunk/premium_tax.cpp
===================================================================
--- lmi/trunk/premium_tax.cpp   2013-04-16 12:14:18 UTC (rev 5684)
+++ lmi/trunk/premium_tax.cpp   2013-04-16 12:15:24 UTC (rev 5685)
@@ -33,10 +33,10 @@
 #include "contains.hpp"
 #include "database.hpp"
 #include "materially_equal.hpp"
-#include "mc_enum_types_aux.hpp" // mc_str()
+#include "mc_enum_types_aux.hpp"        // mc_str()
 #include "stratified_charges.hpp"
 
-#include <algorithm>             // std::max()
+#include <algorithm>                    // std::max()
 
 namespace {
 /// Determine whether premium tax is retaliatory.
@@ -177,8 +177,9 @@
 
 /// Test consistency of premium-tax loads.
 ///
-/// In particular, if the tiered premium-tax load isn't zero, then the
-/// corresponding non-tiered load must be zero.
+/// If the tiered premium-tax load isn't zero, then the corresponding
+/// non-tiered load must be zero, so that the sum of the tiered and
+/// non-tiered portions is the actual load.
 ///
 /// Premium-tax pass-through for AK, DE, and SD insurers is not
 /// supported. If the state of domicile has a tiered rate, then most
@@ -409,8 +410,8 @@
 ///
 /// TAXATION !! No contemporary authority seems to believe that a
 /// change in the premium-tax rate, even if passed through to the
-/// policyowner, is a 7702A material change or a GPT adjustment
-/// event. Therefore, this function will be expunged; but any unique
+/// policyowner, is a 7702A material change or a GPT adjustment event.
+/// Therefore, this function will be expunged; but any unique
 /// commentary or consistency test should be preserved.
 
 double lowest_premium_tax_load
@@ -421,24 +422,6 @@
     ,stratified_charges const& strata
     )
 {
-    // TRICKY !! Here, we use 'DB_PremTaxLoad', not 'DB_PremTaxRate',
-    // to determine the lowest premium-tax load. Premium-tax loads
-    // (charged by the insurer to the contract) and rates (charged by
-    // the state to the insurer) really shouldn't be mixed. The
-    // intention is to support products that pass actual premium tax
-    // through as a load, taking into account retaliation and tiered
-    // premium-tax rates.
-    //
-    // While a more complicated model would be more aesthetically
-    // satisfying, this gives the right answer in practice for the
-    // two cases we believe will arise in practice. In the first case,
-    // premium-tax load doesn't vary by state--perhaps a flat load
-    // such as two percent might be used, or maybe zero percent with
-    // premium-tax expense covered elsewhere in pricing--and tiering
-    // is ignored, so this implementation just returns the flat load.
-    // In the second case, the exact premium tax is passed through,
-    // so the tax rate equals the tax load.
-
     double z = 0.0;
     if(amortize_premium_load)
         {

Modified: lmi/trunk/premium_tax.hpp
===================================================================
--- lmi/trunk/premium_tax.hpp   2013-04-16 12:14:18 UTC (rev 5684)
+++ lmi/trunk/premium_tax.hpp   2013-04-16 12:15:24 UTC (rev 5685)
@@ -26,7 +26,7 @@
 
 #include "config.hpp"
 
-#include "mc_enum_type_enums.hpp" // mcenum_state
+#include "mc_enum_type_enums.hpp"       // mcenum_state
 #include "obstruct_slicing.hpp"
 #include "uncopyable_lmi.hpp"
 
@@ -39,10 +39,31 @@
 ///
 /// Scalar and tiered rates are deliberately maintained in the product
 /// files so that they can be readily examined, transferred to other
-/// systems, and overridden if desired. The values hardcoded here are
-/// generally appropriate, but subject to interpretation because some
-/// states impose assessments in addition to their nominal tax rates.
+/// systems, and overridden if desired. The values hardcoded here and
+/// used as defaults in product files are generally appropriate, but
+/// subject to interpretation because some states impose assessments
+/// in addition to their nominal tax rates.
 ///
+/// Retaliation is handled in the code, so rates specified in the
+/// product database shouldn't reflect retaliation. (If they did, then
+/// different rates would be needed for different domiciles.)
+///
+/// The product database distinguishes premium-tax loads from rates:
+/// 'DB_PremTaxLoad' is the load charged by the insurer against the
+/// contract, while 'DB_PremTaxRate' is the tax rate levied by the
+/// state upon the insurer.
+///
+/// At present, however, '.strata' files contain only the (tiered) tax
+/// rates: there are no distinct tiered tax loads.
+///
+/// Despite that limitation, the correct answer is obtained for the
+/// two cases that have arisen in practice. In the first case, the
+/// premium-tax load doesn't vary by state--perhaps a flat load such
+/// as two percent is used, or maybe zero percent with premium-tax
+/// expense covered elsewhere in pricing--and tiering is ignored, so
+/// the tax load is simply that scalar. In the second case, the exact
+/// premium tax is passed through, so the load equals the tax rate.
+///
 /// Known shortcomings.
 ///
 /// Default values and brackets for tiered rates should be moved here
@@ -59,7 +80,10 @@
 /// been copied here, and portions of 'stratified_charges.cpp' moved
 /// here, retaliation can be made more correct in "tiered" states.
 /// AK and SD retaliate with respect to their initial bands only, but
-/// such retaliation is for now presumed not to occur.
+/// such retaliation is for now presumed not to occur, so AK and SD
+/// domiciles are not supported. Furthermore, retaliation against AK
+/// and SD contracts is not supported, so premium tax is understated
+/// for a few domiciles.
 ///
 /// A greatest-premium-tax-load function is wanted for the approximate
 /// "pay as you go" modal premium (BasicValues::GetModalPremMlyDed()).