fgValidatePath: documentation improvements

diff --git a/src/Main/util.cxx b/src/Main/util.cxx
index 286396784476a8c36eb860459b8dfd14b0c5ee93..65983ce045de3686f0c9b90b01239a9c7d40eb58 100644 (file)
--- a/src/Main/util.cxx
+++ b/src/Main/util.cxx
@@ -75,10 +75,12 @@ fgGetLowPass (double current, double target, double timeratio)
 static string_list read_allowed_paths;
 static string_list write_allowed_paths;
 
-// Allowed paths here are absolute, and may contain _one_ *,
-// which matches any string
-// FG_SCENERY is deliberately not allowed, as it would make
-// /sim/terrasync/scenery-dir a security hole
+/**
+ * Allowed paths here are absolute, and may contain _one_ *,
+ * which matches any string
+ * FG_SCENERY is deliberately not allowed, as it would make
+ * /sim/terrasync/scenery-dir a security hole
+ */
 void fgInitAllowedPaths()
 {
     if(SGPath("ygjmyfvhhnvdoesnotexist").realpath() == "ygjmyfvhhnvdoesnotexist"){
@@ -142,10 +144,13 @@ void fgInitAllowedPaths()
     }
 }
 
-// Check whether Nasal is allowed to access a path
-// Warning: because this always (not just on Windows) converts \ to /,
-// and accepts relative paths (check-to-use race if the current directory
-// changes), always use the returned path not the original one
+/**
+ * Check whether Nasal is allowed to access a path
+ * Warning: because this always (not just on Windows) treats both \ and /
+ * as path separators, and accepts relative paths (check-to-use race if
+ * the current directory changes),
+ * always use the returned path not the original one
+ */
 std::string fgValidatePath (const std::string& path, bool write)
 {
     // Normalize the path (prevents ../../.. or symlink trickery)

diff --git a/src/Main/util.hxx b/src/Main/util.hxx
index 133f1526ec3acdeb6e9e249c28605a81885fbcc2..f078d0fdb3c3860b9a3d83b139137d4e6cad9cb3 100644 (file)
--- a/src/Main/util.hxx
+++ b/src/Main/util.hxx
@@ -40,7 +40,12 @@ double fgGetLowPass (double current, double target, double timeratio);
  * File access control, used by Nasal and fgcommands.
  * @param path Path to be validated
  * @param write True for write operations and false for read operations.
- * @return The validated path on success or 0 if access denied.
+ * @return The validated path on success or empty if access denied.
+ *
+ * Warning: because this always (not just on Windows) treats both \ and /
+ * as path separators, and accepts relative paths (check-to-use race if
+ * the current directory changes),
+ * always use the returned path not the original one
  */
 std::string fgValidatePath(const SGPath& path, bool write);
 std::string fgValidatePath(const std::string& path, bool write);