[lmi-commits] [5207] Improve documentation

[Greg Chicares]

Revision: 5207
          http://svn.sv.gnu.org/viewvc/?view=rev&root=lmi&revision=5207
Author:   chicares
Date:     2011-06-14 16:52:09 +0000 (Tue, 14 Jun 2011)
Log Message:
-----------
Improve documentation

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

Modified: lmi/trunk/ChangeLog
===================================================================
--- lmi/trunk/ChangeLog 2011-06-14 12:14:53 UTC (rev 5206)
+++ lmi/trunk/ChangeLog 2011-06-14 16:52:09 UTC (rev 5207)
@@ -28010,3 +28010,23 @@
 Resolve a marked defect. Extending TieredNetToGross() to keep track of
 unused target premium would not make this code more maintainable.
 
+20110613T1344Z <address@hidden> [648]
+
+  dbdict.cpp
+Improve documentation.
+
+20110614T1214Z <address@hidden> [648]
+
+  Makefile.am
+  dbdict.cpp
+  objects.make
+  premium_tax.cpp
+  premium_tax.hpp
+Move premium-tax rates to a more appropriate place.
+
+20110614T1652Z <address@hidden> [649]
+
+  premium_tax.cpp
+  premium_tax.hpp
+Improve documentation.
+

Modified: lmi/trunk/premium_tax.cpp
===================================================================
--- lmi/trunk/premium_tax.cpp   2011-06-14 12:14:53 UTC (rev 5206)
+++ lmi/trunk/premium_tax.cpp   2011-06-14 16:52:09 UTC (rev 5207)
@@ -234,6 +234,21 @@
         }
 }
 
+/// Reinitialize YTD state variables.
+///
+/// Except for initialization to zero, these variables are used only
+/// by calculate_load() and the trivial const accessor ytd_load(), in
+/// combination with which (and the present function) they may be
+/// thought of as constituting a stateful function subobject.
+///
+/// TODO ?? This is incorrect for inforce. Suppose the tax state has
+/// a tiered rate with a breakpoint that has already been met for an
+/// off-anniversary inforce illustration. Any further payment in the
+/// same year should be taxed at a lower rate. INPUT !! YTD taxable
+/// premium needs to be passed from the admin system; it is not
+/// necessary to pass the other variables, because they can be
+/// calculated here.
+
 void premium_tax::start_new_year()
 {
     ytd_taxable_premium_   = 0.0;
@@ -304,9 +319,6 @@
 /// A single table suffices for every domicile, because retaliation is
 /// explicitly performed elsewhere.
 ///
-/// Exact values are a matter of interpretation, because some states
-/// impose various assessments in addition to their nominal tax rates.
-///
 /// AK and SD have a tiered premium tax that lmi handles; DE has one
 /// that it does not. As elsewhere in lmi, tiered and non-tiered
 /// charges are calculated separately and added together; therefore,

Modified: lmi/trunk/premium_tax.hpp
===================================================================
--- lmi/trunk/premium_tax.hpp   2011-06-14 12:14:53 UTC (rev 5206)
+++ lmi/trunk/premium_tax.hpp   2011-06-14 16:52:09 UTC (rev 5207)
@@ -35,6 +35,43 @@
 class product_database;
 class stratified_charges;
 
+/// Calculate premium tax, particularly when passed through as a load.
+///
+/// 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.
+///
+/// Known shortcomings.
+///
+/// Default values and brackets for tiered rates should be moved here
+/// from 'stratified_charges.cpp', in order to keep all premium-tax
+/// information in one place.
+///
+/// The physical complexity should be reduced by adding a new ctor
+/// that takes as arguments the actual values and brackets read from
+/// the '.strata' and '.database' files, and implementing the existing
+/// ctors in a TU of their own. This would probably suggest physical
+/// improvements to classes Loads and load_details.
+///
+/// Once actual values and brackets read from '.strata' files have
+/// 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.
+///
+/// A greatest-premium-tax-load function is wanted for the approximate
+/// "pay as you go" modal premium (BasicValues::GetModalPremMlyDed()).
+/// At present, that premium is insufficient to prevent instant lapse
+/// in AK and SD when premium tax is passed through as a load.
+///
+/// start_new_year() should be improved as noted in its documentation.
+///
+/// premium_tax_rates_for_annuities() should be implemented.
+///
+/// DATABASE !! 'DB_PremTaxTable' should be eradicated.
+
 class premium_tax
   :        private lmi::uncopyable <premium_tax>
   ,virtual private obstruct_slicing<premium_tax>