From: Mikko Rasa <tdb@tdb.fi>
Date: Fri, 6 Jul 2012 20:47:24 +0000 (+0300)
Subject: Comment updates
X-Git-Url: http://git.tdb.fi/?p=libs%2Fcore.git;a=commitdiff_plain;h=6c958cd2d8806063580f836e4c3d486832af9635

Comment updates
---

diff --git a/source/fs/path.h b/source/fs/path.h
index 9bc93f6..210b5d9 100644
--- 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 &);