[lmi-commits] [lmi] master 1774fba 3/3: Clarify unit-test documentation

[Greg Chicares]

branch: master
commit 1774fba8a1003aa902ee17a453fe2a584d34799d
Author: Gregory W. Chicares <gchicares@sbcglobal.net>
Commit: Gregory W. Chicares <gchicares@sbcglobal.net>

    Clarify unit-test documentation
    
    It does seem unfortunate that boost's free function
      path change_extension(path const& p, std::string const& new_ext);
    was standardized only as non-const member
      path& replace_extension(path const& new_ext = path());
    because almost half of lmi's replace_extension() calls
      $git grep replace_extension
    must take extra care to preserve the argument, e.g.:
      fs::path{cell_filepath}.replace_extension(".test")
    
    It is tempting to add such a free function, not only for convenience
    but also for safety. For now, hypothesized that to have been done,
    and rewrote documentation to be less confusing.
---
 path_utility_test.cpp | 11 +++++++----
 1 file changed, 7 insertions(+), 4 deletions(-)

diff --git a/path_utility_test.cpp b/path_utility_test.cpp
index 2d9d7d2..4f4adc6 100644
--- a/path_utility_test.cpp
+++ b/path_utility_test.cpp
@@ -261,11 +261,14 @@ void test_unique_filepath_with_normal_filenames()
 
     keep_open.close();
 
-    // Verify that the first function call here is redundant:
-    //   path_b = fs::replace_extension(path_a, ext)
-    //   path_c = unique_filepath (path_b, ext)
+    // Verify that the first function call here is redundant
+    // (for a hypothetical free function
+    //   fs::path alter_extension(fs::path const&, fs::path const&)
+    // that doesn't alter its arguments):
+    //   path_b = alter_extension(path_a, ext)
+    //   path_c = unique_filepath(path_b, ext)
     // and this single function call has the same effect:
-    //   path_c = unique_filepath (path_a, ext)
+    //   path_c = unique_filepath(path_a, ext)
     // notably without reduplicating any part of 'ext' if 'ext'
     // contains a noninitial '.'.
     //