[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[lmi-commits] [4836] Consolidate and expand documentation
From: |
Greg Chicares |
Subject: |
[lmi-commits] [4836] Consolidate and expand documentation |
Date: |
Wed, 14 Apr 2010 13:18:15 +0000 |
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()
+{
+}
+
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- [lmi-commits] [4836] Consolidate and expand documentation,
Greg Chicares <=