[lmi-commits] [lmi] master 41274a8 14/33: Improve documentation

[Greg Chicares]

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

    Improve documentation
    
    This change in [squashed] commit e0362c7971676:
    
    -/// fs::change_extension() uses the present argument order:
    -///   function(original, new_part)
    +/// fs::path::replace_extension() uses the present argument order:
    +///   original.replace_extension(new_part)
    
    lost the meaning of the original--i.e., lmi function modify_directory()
    takes two arguments in a particular order, and change_extension() in
    the boost original took two corresponding arguments in the same order.
    Because the standard replace_extension() takes only one argument, there
    is no parallel to be drawn.
---
 path_utility.cpp | 7 +++----
 1 file changed, 3 insertions(+), 4 deletions(-)

diff --git a/path_utility.cpp b/path_utility.cpp
index d68b0b2..0228f4c 100644
--- a/path_utility.cpp
+++ b/path_utility.cpp
@@ -46,11 +46,10 @@
 ///   modify_directory("sh", "/usr/bin") // present order
 ///   modify_directory("/usr/bin", "sh") // opposite order
 /// because the path precedes the filename in canonical form. However,
-/// fs::path::replace_extension() uses the present argument order:
-///   original.replace_extension(new_part)
-/// and in a nondegenerate case such as:
+/// consider a nondegenerate case--this:
 ///   modify_directory("/bin/sh", "/usr/bin") // present order
-/// simply means "change the directory of /bin/sh to /usr/bin", while
+/// naturally means "change the directory of /bin/sh to /usr/bin"
+/// (yielding "/usr/bin/sh"), whereas this:
 ///   modify_directory("/usr/bin", "/bin/sh") // opposite order
 /// seems less natural.
 ///