Comment updates

diff --git a/source/fs/path.h b/source/fs/path.h
index 9bc93f6c003eab2db5a695c2a312c9b1db1fc4c8..210b5d93d14c88bf136d07f25a5ddc78c7fc89e2 100644 (file)
--- a/source/fs/path.h
+++ b/source/fs/path.h
@@ -21,6 +21,12 @@ enum
 Stores a filesystem path.  Paths are always stored in a normalized form; there
 are never any "." or ".." components in the middle of the path, and relative
 paths always begin with a single "." component or a sequence ".." components.
+As a special case, calling the constructor with no arguments or with an empty
+string will construct an empty path; this can be usedful as an invalid value.
+
+A path can also be treated as an array of components, supporting indexing,
+iteration and slicing.  In this context the root directory is treated as a
+component of its own.
 */
 class Path
 {
@@ -59,20 +65,23 @@ private:
        void init(const std::string &);
 
 public:
+       /// Returns the path as a string.
        const std::string &str() const { return path; }
 
        /// Returns the number of components in the path.
        unsigned size() const;
 
+       /** Indicates whether the path is empty.  This really means empty; a path
+       pointing to the current directory is not empty. */
        bool empty() const { return path.empty(); }
 
-       /// Determines whether the path starts from the root directory
+       /// Determines whether the path starts from the root directory.
        bool is_absolute() const;
 
        /// Extracts a range of components from the path.
        Path subpath(unsigned start, unsigned count = static_cast<unsigned>(-1)) const;
 
-       /// Concatenates this path with another one, with usual filesystem semantics
+       /// Concatenates this path with another one, with usual filesystem semantics.
        Path operator/(const Path &p) const;
        Path &operator/=(const Path &);