[lmi-commits] [4836] Consolidate and expand documentation

[Greg Chicares]

Revision: 4836
          http://svn.sv.gnu.org/viewvc/?view=rev&root=lmi&revision=4836
Author:   chicares
Date:     2010-04-14 13:18:15 +0000 (Wed, 14 Apr 2010)
Log Message:
-----------
Consolidate and expand documentation

Modified Paths:
--------------
    lmi/trunk/ChangeLog
    lmi/trunk/input_xml_io.cpp
    lmi/trunk/mec_input.cpp
    lmi/trunk/mec_state.cpp
    lmi/trunk/xml_serializable.tpp

Modified: lmi/trunk/ChangeLog
===================================================================
--- lmi/trunk/ChangeLog 2010-04-11 20:37:23 UTC (rev 4835)
+++ lmi/trunk/ChangeLog 2010-04-14 13:18:15 UTC (rev 4836)
@@ -24835,3 +24835,17 @@
   product_file_test.cpp
 Refactor read-only access to class product_data.
 
+20100414T1318Z <address@hidden> [760]
+
+  input_xml_io.cpp
+  mec_input.cpp
+  mec_state.cpp
+  xml_serializable.tpp
+Consolidate and expand documentation. For virtual functions, meaty
+documentation in the base class and nothing in derived classes is
+better than nothing in the base class and a one-liner cut and pasted
+in derived classes, especially since doxygen links derived-class
+implementations to the base-class documentation for each documented
+virtual. It does no harm to provide an empty implementation of a pure
+virtual merely as a hook upon which to hang documentation.
+

Modified: lmi/trunk/input_xml_io.cpp
===================================================================
--- lmi/trunk/input_xml_io.cpp  2010-04-11 20:37:23 UTC (rev 4835)
+++ lmi/trunk/input_xml_io.cpp  2010-04-14 13:18:15 UTC (rev 4836)
@@ -121,8 +121,6 @@
     return v.end() != std::find(v.begin(), v.end(), s);
 }
 
-/// Provide for backward compatibility before assigning values.
-
 std::string Input::redintegrate_ex_ante
     (int                file_version
     ,std::string const& name
@@ -281,8 +279,6 @@
     return new_value;
 }
 
-/// Provide for backward compatibility after assigning values.
-
 void Input::redintegrate_ex_post
     (int                                file_version
     ,std::map<std::string, std::string> detritus_map
@@ -390,8 +386,6 @@
         }
 }
 
-/// Perform any required after-the-fact fixup.
-
 void Input::redintegrate_ad_terminum()
 {
     if(EffectiveDateToday.value() && 
!global_settings::instance().regression_testing())

Modified: lmi/trunk/mec_input.cpp
===================================================================
--- lmi/trunk/mec_input.cpp     2010-04-11 20:37:23 UTC (rev 4835)
+++ lmi/trunk/mec_input.cpp     2010-04-14 13:18:15 UTC (rev 4836)
@@ -631,8 +631,6 @@
     return v.end() != std::find(v.begin(), v.end(), s);
 }
 
-/// Provide for backward compatibility before assigning values.
-
 std::string mec_input::redintegrate_ex_ante
     (int                file_version
     ,std::string const& // name
@@ -650,8 +648,6 @@
         }
 }
 
-/// Provide for backward compatibility after assigning values.
-
 void mec_input::redintegrate_ex_post
     (int                                file_version
     ,std::map<std::string, std::string> // detritus_map
@@ -668,8 +664,6 @@
         }
 }
 
-/// Perform any required after-the-fact fixup.
-
 void mec_input::redintegrate_ad_terminum()
 {
     Reconcile();

Modified: lmi/trunk/mec_state.cpp
===================================================================
--- lmi/trunk/mec_state.cpp     2010-04-11 20:37:23 UTC (rev 4835)
+++ lmi/trunk/mec_state.cpp     2010-04-14 13:18:15 UTC (rev 4836)
@@ -410,8 +410,6 @@
     return v.end() != std::find(v.begin(), v.end(), s);
 }
 
-/// Provide for backward compatibility before assigning values.
-
 std::string mec_state::redintegrate_ex_ante
     (int                file_version
     ,std::string const& // name
@@ -429,8 +427,6 @@
         }
 }
 
-/// Provide for backward compatibility after assigning values.
-
 void mec_state::redintegrate_ex_post
     (int                                file_version
     ,std::map<std::string, std::string> // detritus_map
@@ -447,8 +443,6 @@
         }
 }
 
-/// Perform any required after-the-fact fixup.
-
 void mec_state::redintegrate_ad_terminum()
 {
 }

Modified: lmi/trunk/xml_serializable.tpp
===================================================================
--- lmi/trunk/xml_serializable.tpp      2010-04-11 20:37:23 UTC (rev 4835)
+++ lmi/trunk/xml_serializable.tpp      2010-04-14 13:18:15 UTC (rev 4836)
@@ -194,3 +194,73 @@
         }
 }
 
+/// Provide for backward compatibility before assigning values.
+///
+/// Motivation: transform an old enumerative string to a contemporary
+/// equivalent, before assigning it to a variable of mc_enum type for
+/// which it would no longer be syntactically valid.
+///
+/// For example, if gender had formerly been stored as {M, F} but now
+/// {Male, Female} is used instead, then this function would be
+/// overridden to transform the old representation to the new:
+///   <gender>M</gender> --> <gender>Male</gender>
+/// This transformation avoids attempting to assign 'M' to a 'gender'
+/// enumeration, which would elicit a runtime error.
+///
+/// The element's text contents are given as a string argument; the
+/// transformed contents are returned as a string.
+
+std::string redintegrate_ex_ante
+    (int                file_version
+    ,std::string const& name
+    ,std::string const& value
+    ) const
+{
+}
+
+/// Provide for backward compatibility after assigning values.
+///
+/// Motivation: transform an old value that remains syntactically
+/// valid but is no longer semantically inappropriate due to changes
+/// in code that uses it; or assign an appropriate default for an
+/// element that was not present in earlier versions.
+///
+/// For example, if a person's first and last names had been stored
+/// separately but are now combined in a single element, then this
+/// function would be overridden to transform this:
+///   <firstname>John</firstname> <lastname>Brown</lastname>
+/// to this:
+///   <name>John Brown</name>
+///
+/// As another example, suppose issue and effective dates are now
+/// distinguished, whereas formerly only issue date had been stored.
+/// It would be reasonable to override this function to copy the
+/// issue-date value to a new effective date element.
+///
+/// The 'residuary_names' argument contains all element tags actually
+/// found in the xml being read that have not yet been processed. This
+/// is useful for verifying that an element expected not to be present
+/// is actually not specified.
+///
+/// The 'detritus_map' argument contains names and values of all tags
+/// that have already been processed if they were marked as detritus:
+/// i.e., if they were used only in an earlier version. In the first
+/// example above, 'firstname' and 'lastname' would be "detritus".
+
+void redintegrate_ex_post
+    (int                                file_version
+    ,std::map<std::string, std::string> detritus_map
+    ,std::list<std::string>             residuary_names
+    )
+{
+}
+
+/// Perform any required after-the-fact fixup.
+///
+/// Override this function to do anything that's necessary after all
+/// elements have been read, but doesn't fit anywhere else.
+
+void redintegrate_ad_terminum()
+{
+}
+