[lmi-commits] [lmi] master ccdffc3 1/4: Improve style and documentation

[Greg Chicares]

branch: master
commit ccdffc3657cd5cc9836fb7efeebed51d424a0ac4
Author: Gregory W. Chicares <address@hidden>
Commit: Gregory W. Chicares <address@hidden>

    Improve style and documentation
    
    See:
      http://lists.nongnu.org/archive/html/lmi/2017-02/msg00060.html
    
    Rewrote the documentation of member template initialize_from_vector(),
    specifically omitting comments that described how it is implemented
    because they seemed unhelpful at best.
---
 input_sequence.cpp | 47 ++++++++++++++++++++---------------------------
 1 file changed, 20 insertions(+), 27 deletions(-)

diff --git a/input_sequence.cpp b/input_sequence.cpp
index d3d44e9..ba404cd 100644
--- a/input_sequence.cpp
+++ b/input_sequence.cpp
@@ -143,8 +143,7 @@ InputSequence::InputSequence
 
 InputSequence::InputSequence(std::vector<double> const& v)
     :years_to_maturity_(v.size())
-    ,number_result_    {v}
-    ,keyword_result_   {}
+    ,number_result_    (v)
 {
     initialize_from_vector(v);
     assert_sane_and_ordered_partition(intervals_, years_to_maturity_);
@@ -157,8 +156,7 @@ InputSequence::InputSequence(std::vector<double> const& v)
 
 InputSequence::InputSequence(std::vector<std::string> const& v)
     :years_to_maturity_(v.size())
-    ,number_result_    {}
-    ,keyword_result_   {v}
+    ,keyword_result_   (v)
 {
     initialize_from_vector(v);
     assert_sane_and_ordered_partition(intervals_, years_to_maturity_);
@@ -184,29 +182,24 @@ void set_value(ValueInterval& v, std::string const& s)
 }
 } // Unnamed namespace.
 
-// Constructors taking only one (vector) argument are used to convert
-// flat vectors with one value per year to input sequences, compacted
-// with run-length encoding.
-//
-// The control constructs may appear nonobvious. This design treats
-// the push_back operation as fundamental: push_back is called exactly
-// when we know that a new interval must be added. This avoids special
-// handling
-//   when the vectors are of length zero, and
-//   for the last interval.
-// As a consequence, we always push_back a dummy interval exactly when
-// we know that it will be needed, and then write to intervals_.back().
-//
-// An alternative design would work with a temporary interval and
-// call push_back as needed. I tried that and concluded that this
-// design is simpler.
-//
-// Strings in input vectors are not validated against a map of
-// permissible strings: these constructors are designed for use only
-// with vectors of strings generated by the program from known-valid
-// input, and should not be used in any other situation.
-// SOMEDAY !! Ideally, therefore, they should be protected from
-// unintended use.
+/// Convert vector to input sequence (ctor helper).
+///
+/// Constructors taking only one (vector) argument use this function
+/// template to convert vectors (with one value per year) to input
+/// sequences (compacted with RLE).
+///
+/// Sets only one of {keyword_result_, number_result_}. The other
+/// defaults to an empty vector (the calling ctor doesn't necessarily
+/// know an appropriate default for its elements, so it can't have any
+/// other size than zero).
+///
+/// When the argument is a vector of strings, presumes that all its
+/// elements are all valid (the calling ctor doesn't know what strings
+/// are permissible).
+///
+/// As these comments suggest, the ctors that use this function
+/// template are suitable only for certain specialized purposes where
+/// the argument is known to be valid.
 
 template<typename T>
 void InputSequence::initialize_from_vector(std::vector<T> const& v)