better comments in PathUtilities.cpp

src/lib/common/PathUtilities.cpp

@@ -15,6 +15,19 @@
 * along with this program.  If not, see <http://www.gnu.org/licenses/>.
 */
 
+/*
+
+These functions cover the vast majority of cases for different paths across
+windows and unixes. They are not, however, fullproof and probably don't cover
+fringe cases very well. The library below might be used as an alternative if
+these implementations prove to be insufficient. As the library's readme states
+it is simply a temporary band-aid until std::filesystem is integrated (C++17
+has it in std::experimental) and this class should also be treated as such.
+
+https://github.com/wjakob/filesystem/
+
+*/
+
 #include "PathUtilities.h"
 
 // keep the default platform delimiter as the first in the list
@@ -41,22 +54,22 @@ std::string PathUtilities::concat(const std::string& left, const std::string& ri
         ++leftEnd;
     auto rightStart = right.find_first_not_of(Delimiters, 0);
     if (rightStart == std::string::npos) {
-        // l/r empty
+        // both left/right are empty
         if (left.size() == 0 && right.size() == 0)
             return "";
-        // r useless, l okay
+        // right is full of delims, left is okay
         if (leftEnd > 0)
             return left.substr(0, leftEnd);
-        // both useless but one has a delim
+        // both left/right useless but at least one has delims
         return std::string(1, DefaultDelimiter);
     }
     if (leftEnd == 0) {
-        // r okay and not prefixed with delims, l empty
+        // right is okay and not prefixed with delims, left is empty
         if (left.size() == 0 && rightStart == 0)
             return right.substr(rightStart);
-        // r okay and prefixed with delims OR l full of delims
+        // (right is okay and prefixed with delims) OR left is full of delims
         return DefaultDelimiter + right.substr(rightStart);
     }
-    // normal concatenation
+    // concatenation using both left and right
     return left.substr(0, leftEnd) + DefaultDelimiter + right.substr(rightStart);
 }