[#175,!414] Addressed more review comments

src/lib/util/boost_time_utils.*
    renamed DEFAULT_FRAC_SECS to MAX_FSECS_PRECISION
    added commentary and fixed indentation

src/lib/util/tests/boost_time_utils_unittest.cc
    added commentary

src/lib/util/boost_time_utils.cc

@@ -28,9 +28,11 @@ isc::util::durationToText(boost::posix_time::time_duration dur, size_t fsecs_pre
       << ":" << std::setw(2) << std::setfill('0') << dur.minutes()
       << ":" << std::setw(2) << std::setfill('0') << dur.seconds();
 
+    // If the requested precision is less than the maximum native precision
+    // we will divide the fractional seconds value by 10^(max - requested)
     if (fsecs_precision) {
         size_t fsecs = dur.fractional_seconds();
-        size_t width = DEFAULT_FRAC_SECS;
+        size_t width = MAX_FSECS_PRECISION;
         if (fsecs_precision < width) {
             for (auto i = 0; i < width - fsecs_precision; ++i) {
                 fsecs /= 10;
@@ -39,9 +41,9 @@ isc::util::durationToText(boost::posix_time::time_duration dur, size_t fsecs_pre
             width = fsecs_precision;
         }
 
-      s << "." << std::setw(width)
+        s << "." << std::setw(width)
-        << std::setfill('0')
+          << std::setfill('0')
-        << fsecs;
+          << fsecs;
     }
 
     return (s.str());

src/lib/util/boost_time_utils.h

@@ -13,7 +13,9 @@
 namespace isc {
 namespace util {
 
-const size_t DEFAULT_FRAC_SECS=boost::posix_time::time_duration::num_fractional_digits();
+/// @brief The number of digits of fractional seconds supplied by the
+/// underlying class, boost::posix_time.  Typically 6 = microseconds.
+const size_t MAX_FSECS_PRECISION=boost::posix_time::time_duration::num_fractional_digits();
 
 /// @brief Converts ptime structure to text
 ///
@@ -33,7 +35,7 @@ const size_t DEFAULT_FRAC_SECS=boost::posix_time::time_duration::num_fractional_
 ///
 /// @return a string representing time
 std::string ptimeToText(boost::posix_time::ptime t,
-                        size_t fsecs_precision = DEFAULT_FRAC_SECS);
+                        size_t fsecs_precision = MAX_FSECS_PRECISION);
 
 /// @brief Converts StatsDuration to text
 ///
@@ -46,7 +48,7 @@ std::string ptimeToText(boost::posix_time::ptime t,
 ///
 /// @return a string representing time
 std::string durationToText(boost::posix_time::time_duration dur,
-                          size_t fsecs_precision = DEFAULT_FRAC_SECS);
+                          size_t fsecs_precision = MAX_FSECS_PRECISION);
 
 }; // end of isc::util namespace
 }; // end of isc namespace

src/lib/util/tests/boost_time_utils_unittest.cc

@@ -25,17 +25,24 @@ TEST(BoostTimeUtilsTest, epoch) {
     time_t tepoch = 0;
     ptime pepoch = from_time_t(tepoch);
 
+    // We're going to loop through precision values starting with 0 throug 
+    // the max supported precision.  Each pass should after the first, should
+    // add an additional level of precision: secs, secs/10, secs/100,
+    // secs/1000 and so on.  The initial string has no fraction seconds.
     std::string expected("1970-01-01 00:00:00");
     std::string sepoch;
-    for (int precision = 0; precision <= DEFAULT_FRAC_SECS; ++precision) {
+    for (int precision = 0; precision <= MAX_FSECS_PRECISION; ++precision) {
         if (precision == 1) {
+            // Adding fractional seconds so we need append a decimal point.
             expected.push_back('.');
         }
 
         if (precision >= 1) {
+            // Adding an additional level of precision, append a zero.
             expected.push_back('0');
         }
 
+        // Now let's see if we get the correct precision in the text.
         sepoch = ptimeToText(pepoch, precision);
         EXPECT_EQ(expected, sepoch) << " test precision:" << precision;
     }
@@ -47,7 +54,7 @@ TEST(BoostTimeUtilsTest, epoch) {
 
     // Now test a requested precision beyond default.  We should
     // get the default precision.
-    sepoch = ptimeToText(pepoch, DEFAULT_FRAC_SECS + 1);
+    sepoch = ptimeToText(pepoch, MAX_FSECS_PRECISION + 1);
     EXPECT_EQ(expected, sepoch);
 
 }
@@ -58,16 +65,24 @@ TEST(BoostTimeUtilsTest, bastilleDay) {
         hours(12) + minutes(13) + seconds(14) + milliseconds(500);
     ptime pbast(date(2015, Jul, 14), tdbast);
 
+    // We're going to loop through precision values starting with 0 throug 
+    // the max supported precision.  Each pass should after the first, should
+    // add an additional level of precision: secs, secs/10, secs/100,
+    // secs/1000 and so on.  The initial string has no fraction seconds.
     std::string expected("2015-07-14 12:13:14");
     std::string sbast;
-    for (int precision = 0; precision <= DEFAULT_FRAC_SECS; ++precision) {
+    for (int precision = 0; precision <= MAX_FSECS_PRECISION; ++precision) {
         if (precision == 1) {
+            // Adding fractional seconds so we need append a decimal point
+            // and the digit 5 (i.e. 500 ms = .5 secs).
             expected.push_back('.');
             expected.push_back('5');
         } else if (precision > 1) {
+            // Adding an additional level of precision, append a zero.
             expected.push_back('0');
         }
 
+        // Now let's see if we get the correct precision in the text.
         sbast = ptimeToText(pbast, precision);
         EXPECT_EQ(expected, sbast) << " test precision:" << precision;
     }
@@ -79,6 +94,6 @@ TEST(BoostTimeUtilsTest, bastilleDay) {
 
     // Now test a requested precision beyond default.  We should
     // get the default precision.
-    sbast = ptimeToText(pbast, DEFAULT_FRAC_SECS + 1);
+    sbast = ptimeToText(pbast, MAX_FSECS_PRECISION + 1);
     EXPECT_EQ(expected, sbast);
 }