[lmi-commits] [lmi] master 4ab2c4e 20/33: Further improve modify_directory() documentation

[Greg Chicares]

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

    Further improve modify_directory() documentation
    
    Prefer posix terminology in documentation:
    
    - the path precedes the leaf        // boost: pretty clear
    - the path precedes the filename    // std::filename: less clear
    + the dirname precedes the basename // posix: clearest of all
---
 path_utility.cpp | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

diff --git a/path_utility.cpp b/path_utility.cpp
index a954def..151fa35 100644
--- a/path_utility.cpp
+++ b/path_utility.cpp
@@ -54,8 +54,8 @@
 /// Arguably the arguments should be given in the opposite order:
 ///   modify_directory("sh", "/usr/bin") // present order
 ///   modify_directory("/usr/bin", "sh") // opposite order
-/// because the path precedes the filename in canonical form. However,
-/// consider a nondegenerate case--this:
+/// because the dirname precedes the basename in canonical form.
+/// However, consider a nondegenerate case--this:
 ///   modify_directory("/bin/sh", "/usr/bin") // present order
 /// naturally means "change the directory of /bin/sh to /usr/bin"
 /// (yielding "/usr/bin/sh"), whereas this:
@@ -71,7 +71,8 @@
 /// actual existing directory.
 ///
 /// std::filesystem provides no way to test whether a path has the form
-/// of a directory. Its fs::is_directory() asks the operating system:
+/// of a directory. Its fs::is_directory() asks the operating system
+/// whether or not a directory exists, so
 ///   is_directory("/usr/lib")
 /// returns 'true' iff the OS reports that such a directory exists;
 /// but the same function call would return 'false' after