Move documentation from Path.cpp to Path.dox

And clean it up a bit. Kept brief description in source.
* Also added Axel to authors in Path.dox and Path.cpp because his name
  appears in git blame as working on the docs and code for the file.
  I hope he doesn't mind.

docs/user/storage/Path.dox

@@ -0,0 +1,503 @@
+/*
+ * Copyright 2002-2013 Haiku Inc. All rights reserved.
+ * Distributed under the terms of the MIT License.
+ *
+ * Authors:
+ *		Tyler Dauwalder
+ *		Axel Dörfler, [email protected]
+ *		John Scipione, [email protected]
+ *		Ingo Weinhold, [email protected]
+ *
+ * Corresponds to:
+ *		headers/os/storage/Path.h	hrev45260
+ *		src/kits/storage/Path.cpp	hrev45260
+ */
+
+
+/*!
+	\file Path.h
+	\ingroup storage
+	\ingroup libbe
+	Provides the BPath class.
+*/
+
+
+/*!
+	\class BPath
+	\ingroup storage
+	\ingroup libbe
+	\brief A class representing a file system path.
+*/
+
+
+/*!
+	\fn BPath::BPath()
+	\brief Creates an uninitialized BPath object.
+
+	\see SetTo()
+*/
+
+
+/*!
+	\fn BPath::BPath(const BPath& path)
+	\brief Creates a copy of the given BPath object.
+
+	\param path the object to be copied.
+*/
+
+
+/*!
+	\fn BPath::BPath(const entry_ref* ref)
+	\brief Creates a BPath object and initializes it to the filesystem entry
+	       specified by the passed in entry_ref struct.
+
+	\param ref the entry_ref to initialize from.
+*/
+
+
+/*!
+	\fn BPath::BPath(const BEntry* entry)
+	\brief Creates a BPath object and initializes it to the filesystem entry
+	       specified by the passed in BEntry object.
+
+	\param entry the BEntry object to initialize from.
+*/
+
+
+/*!
+	\fn BPath::BPath(const char* dir, const char* leaf, bool normalize)
+	\brief Creates a BPath object and initializes it to the specified path or
+	       path and filename combination.
+
+	\param dir The base component of the pathname. May be absolute or relative.
+	       If relative, it is based off the current working directory.
+	\param leaf The (optional) leaf component of the pathname. Must be
+	       relative. The value of \a leaf is concatenated to the end of \a dir
+	       (a "/" will be added as a separator, if necessary).
+	\param normalize boolean flag used to force normalization; normalization
+	       may sometimes occur even if \c false. The following items require
+	       normalization:
+	       - Relative pathnames (after concatenation; e.g. "boot/ltj")
+	       - The presence of "." or ".." ("/boot/ltj/../ltj/./gwar")
+	       - Redundant slashes ("/boot//ltj")
+	       - A trailing slash ("/boot/ltj/")
+	
+*/
+
+
+/*!
+	\fn BPath::BPath(const BDirectory* dir, const char* leaf, bool normalize)
+	\brief Creates a BPath object and initializes it to the specified directory
+	       and filename combination.
+
+	\param dir The directory that provides the base component of the pathname.
+	\param leaf The (optional) leaf component of the pathname. Must be
+	       relative. The value of \a leaf is concatenated to the end of \a dir
+	       (a "/" will be added as a separator, if necessary).
+	\param normalize boolean flag used to force normalization; normalization
+	       may sometimes occur even if \c false. The following items require
+	       normalization:
+	       - Relative pathnames (after concatenation; e.g. "boot/ltj")
+	       - The presence of "." or ".." ("/boot/ltj/../ltj/./gwar")
+	       - Redundant slashes ("/boot//ltj")
+	       - A trailing slash ("/boot/ltj/")
+*/
+
+
+/*!
+	\fn BPath::~BPath()
+	\brief Destroys the BPath object and frees any of its associated resources.
+*/
+
+
+/*!
+	\name Constructor helper methods
+*/
+
+
+//! @{
+
+
+/*!
+	\fn status_t BPath::InitCheck() const
+	\brief Checks whether or not the object was properly initialized.
+
+	\return \c B_OK, if the BPath object was properly initialized, an error
+	        code otherwise.
+*/
+
+
+/*!
+	\fn status_t BPath::SetTo(const entry_ref* ref)
+	\brief Reinitializes the object to the filesystem entry specified by the
+	       passed in entry_ref struct.
+	\param ref The entry_ref to reinitialize the entry from.
+
+	\returns A status code.
+	\retval B_OK Initialization was successful.
+	\retval B_BAD_VALUE \c NULL \a ref.
+	\retval B_NAME_TOO_LONG The pathname was longer than \c B_PATH_NAME_LENGTH.
+*/
+
+
+/*!
+	\fn status_t BPath::SetTo(const BEntry* entry)
+	\brief Reinitializes the object to the specified filesystem entry.
+
+	\param entry The BEntry to reinitialize the entry from.
+
+	\returns A status code.
+	\retval B_OK Initialization was successful.
+	\retval B_BAD_VALUE \c NULL \a ref.
+	\retval B_NAME_TOO_LONG The pathname was longer than \c B_PATH_NAME_LENGTH.
+*/
+
+
+/*!
+	\fn status_t BPath::SetTo(const char* path, const char* leaf, bool normalize)
+	\brief Reinitializes the object to the passed in \a path or \a path and
+	       \a leaf combination.
+
+	\remarks The following pseudocode is safe:
+	         \code path.SetTo(path.Path(), "new leaf") \endcode
+
+	\param path The \a path name to use.
+	\param leaf The \a leaf name to use (may be \c NULL).
+	\param normalize Boolean flag used to force normalization; normalization
+	       may sometimes occur even if \c false. The following items require
+	       normalization:
+	       - Relative pathnames (after concatenation; e.g. "boot/ltj")
+	       - The presence of "." or ".." ("/boot/ltj/../ltj/./gwar")
+	       - Redundant slashes ("/boot//ltj")
+	       - A trailing slash ("/boot/ltj/")
+
+	\returns A status code.
+	\retval B_OK Initialization was successful.
+	\retval B_BAD_VALUE \c NULL \a ref.
+	\retval B_NAME_TOO_LONG The pathname was longer than \c B_PATH_NAME_LENGTH.
+*/
+
+
+/*!
+	\fn status_t BPath::SetTo(const BDirectory* dir, const char* path,
+		bool normalize)
+	\brief Reinitializes the object to the passed in \a dir and relative
+	       \a path combination.
+
+	\param dir The directory that provides the base component of the pathname.
+	\param path the relative \a path name (may be \c NULL).
+	\param normalize boolean flag used to force normalization; normalization
+	       may sometimes occur even if \c false. The following items require
+	       normalization:
+	       - Relative pathnames (after concatenation; e.g. "boot/ltj")
+	       - The presence of "." or ".." ("/boot/ltj/../ltj/./gwar")
+	       - Redundant slashes ("/boot//ltj")
+	       - A trailing slash ("/boot/ltj/")
+
+	\returns A status code.
+	\retval B_OK Initialization was successful.
+	\retval B_BAD_VALUE \c NULL \a ref.
+	\retval B_NAME_TOO_LONG The pathname was longer than \c B_PATH_NAME_LENGTH.
+*/
+
+
+/*!
+	\fn void BPath::Unset()
+	\brief Returns the object to an uninitialized state.
+	
+	Frees any resources it allocated and marks the object as uninitialized.
+*/
+
+
+//! @}
+
+
+/*!
+	\name Path manipulation methods
+*/
+
+
+//! @{
+
+
+/*!
+	\fn status_t BPath::Append(const char* path, bool normalize)
+	\brief Appends the passed in relative path to the end of the current path.
+
+	This method fails if the path is absolute or the BPath object is
+	uninitialized.
+
+	\param path Relative pathname to append to current path (may be \c NULL).
+	\param normalize Boolean flag used to force normalization; normalization
+	       may sometimes occur even if \c false. The following items require
+	       normalization:
+	       - Relative pathnames (after concatenation; e.g. "boot/ltj")
+	       - The presence of "." or ".." ("/boot/ltj/../ltj/./gwar")
+	       - Redundant slashes ("/boot//ltj")
+	       - A trailing slash ("/boot/ltj/")
+
+	\returns A status code.
+	\retval B_OK Initialization was successful.
+	\retval B_BAD_VALUE \c NULL \a ref.
+	\retval B_NAME_TOO_LONG The pathname was longer than \c B_PATH_NAME_LENGTH.
+*/
+
+
+//! @}
+
+
+/*!
+	\name Path information methods
+*/
+
+
+//! @{
+
+
+/*!
+	\fn const char* BPath::Path() const
+	\brief Gets the entire path of the object.
+
+	\returns The path name of the object, or \c NULL if it is not properly
+	         initialized.
+*/
+
+
+/*!
+	\fn const char* BPath::Leaf() const
+	\brief Gets the leaf portion of the path.
+
+	The leaf portion of the path is defined to be the string after the last
+	\c '/'. For the root path (\c "/") it is an empty string (\c "").
+
+	\returns The leaf portion of the path or \c NULL if it is not properly
+	         initialized.
+*/
+
+
+/*!
+	\fn status_t BPath::GetParent(BPath* path) const
+	\brief Initializes \a path with the parent directory of the BPath object.
+
+	No normalization is performed on the path.
+
+	\param path The BPath object to be initialized to the parent directory.
+
+	\returns A status code.
+	\retval B_OK Everything went fine.
+	\retval B_BAD_VALUE \c NULL \a path.
+	\retval B_ENTRY_NOT_FOUND The BPath object represents the root path and
+	        thus has no parent.
+*/
+
+
+/*!
+	\fn bool BPath::IsAbsolute() const
+	\brief Gets whether or not the path is absolute or relative.
+
+	\warning This method returns \c false if the object is initialized.
+
+	\returns \c true if the path is absolute, \c false if relative or if the
+	         object is uninitialized.
+*/
+
+
+//! @}
+
+
+/*!
+	\name Operator overload methods
+*/
+
+
+//! @{
+
+
+/*!
+	\fn bool BPath::operator==(const BPath& item) const
+	\brief Performs a simple (string-wise) comparison of paths for equality.
+
+	\warning No normalization takes place, two uninitialized BPath objects are
+	         considered equal.
+
+	\param item the BPath object to compare.
+
+	\return \c true, if the paths are equal, \c false otherwise.
+*/
+
+
+/*!
+	\fn bool BPath::operator==(const char* path) const
+	\brief Performs a simple (string-wise) comparison of paths for equality.
+
+	\warning No normalization takes place.
+
+	\param path The path to compare.
+
+	\return \c true, if the path names are equal, \c false otherwise.
+*/
+
+
+/*!
+	\fn bool BPath::operator!=(const BPath& item) const
+	\brief Performs a simple (string-wise) comparison of paths for inequality.
+
+	\warning No normalization takes place, two uninitialized BPath objects are
+	         considered equal.
+
+	\param item the BPath object to compare.
+
+	\return \c true, if the path names are \b not equal, \c false otherwise.
+*/
+
+
+/*!
+	\fn bool BPath::operator!=(const char* path) const
+	\brief Performs a simple (string-wise) comparison of paths for inequality.
+
+	\warning No normalization takes place.
+
+	\param path The path to compare.
+
+	\return \c true, if the path names are \b not equal, \c false otherwise.
+*/
+
+
+/*!
+	\fn BPath& BPath::operator=(const BPath& item)
+	\brief Initializes the object as a copy of \a item.
+
+	\param item The BPath object to copy
+
+	\return A pointer to the newly initialized BPath object.
+*/
+
+
+/*!
+	\fn BPath& BPath::operator=(const char* path)
+	\brief Initializes the object with the passed in \a path.
+
+	Has the same effect as \code SetTo(path) \endcode
+
+	\param path the path to be assign to this object.
+
+	\return A pointer to the newly initialized BPath object.
+*/
+
+
+//! @}
+
+
+/*!
+	\name BFlattenable override methods
+*/
+
+
+//! @{
+
+
+/*!
+	\fn bool BPath::IsFixedSize() const
+	\brief Overrides BFlattenable::IsFixedSize(). Always returns \c false.
+
+	\return \c false
+*/
+
+
+/*!
+	\fn type_code BPath::TypeCode() const
+	\brief Overrides BFlattenable::TypeCode() Always returns \c B_REF_TYPE.
+
+	\return \c B_REF_TYPE
+*/
+
+
+/*!
+	\fn ssize_t BPath::FlattenedSize() const
+	\brief Overrides BFlattenable::FlattenedSize() Gets the size of the
+	       flattened entry_ref struct that represents the path in bytes.
+
+	\return The size of the flattened entry_ref struct that represents the
+	        path in bytes.
+*/
+
+
+/*!
+	\fn status_t BPath::Flatten(void* buffer, ssize_t size) const
+	\brief Overrides BFlattenable::Flatten(). Converts the path of the object
+	       to an entry_ref and writes it into <em>buffer</em>.
+
+	\param buffer The buffer that the data is to be stored in.
+	\param size Size of <em>buffer</em>.
+
+	\returns A status code.
+	\retval B_OK Everything went fine.
+	\retval B_BAD_VALUE \c NULL buffer or the buffer is of insufficient size.
+*/
+
+
+/*!
+	\fn bool BPath::AllowsTypeCode(type_code code) const
+	\brief Overrides BFlattenable::AllowsTypeCode(). Checks if type code is
+	       equal to \c B_REF_TYPE.
+
+	\param code The type code to test.
+
+	\return \c true if code is \c B_REF_TYPE, \c false otherwise.
+*/
+
+
+/*!
+	\fn status_t BPath::Unflatten(type_code code, const void* buffer,
+		ssize_t size)
+	\brief Overrides BFlattenable::Unflatten(). Initializes the object with
+	       the flattened entry_ref data from the passed in buffer.
+
+	The type code must be set to \c B_REF_TYPE.
+
+	\param code The type code of the flattened data, must be \c B_REF_TYPE.
+	\param buf A pointer to the flattened data.
+	\param size The size of \a buffer in bytes.
+
+	\returns A status code.
+	\retval B_OK Everything went fine.
+	\retval B_BAD_VALUE \a buffer is \c NULL or doesn't contain an entry_ref.
+*/
+
+
+//! @}
+
+
+/// private methods, won't show up in docs
+
+
+/*!
+	status_t BPath::_SetPath(const char* path)
+	\brief Sets the supplied path.
+
+	The path is copied. If \a path is \c NULL path of the object is set to
+	\c NULL as well. The object's old path is deleted.
+
+	\param path the path to be set
+
+	\returns A status code.
+	\retval B_OK Everything went fine.
+	\retval B_NO_MEMORY Insufficient memory.
+*/
+
+
+/*!
+	bool BPath::_MustNormalize(const char* path, status_t* _error)
+	\brief Checks a path to see if normalization is required.
+
+	The following items require normalization:
+	- Relative pathnames (after concatenation; e.g. "boot/ltj")
+	- The presence of "." or ".." ("/boot/ltj/../ltj/./gwar")
+	- Redundant slashes ("/boot//ltj")
+	- A trailing slash ("/boot/ltj/")
+
+	\param _error A pointer to an error variable that will be set if the input
+		is not a valid path.
+
+	\return \c true if \a path requires normalization, \c false otherwise.
+*/

headers/os/storage/Path.h

@@ -76,7 +76,9 @@ private:
 			uint32			_reserved[4];
 
 			char*			fName;
+								// Pointer to the path string of the object.
 			status_t		fCStatus;
+								// The initialization status of the object.
 };
 
 #endif	// _PATH_H

src/kits/storage/Path.cpp

@@ -4,16 +4,11 @@
  *
  * Authors:
  *		Tyler Dauwalder
+ *		Axel Dörfler, [email protected]
  *		Ingo Weinhold, [email protected]
  */
 
 
-/*!
-	\file Path.cpp
-	BPath implementation.
-*/
-
-
 #include <Path.h>
 
 #include <new>
@@ -30,7 +25,7 @@
 using namespace std;
 
 
-//! Creates an uninitialized BPath object.
+// Creates an uninitialized BPath object.
 BPath::BPath()
 	:
 	fName(NULL),
@@ -39,9 +34,7 @@ BPath::BPath()
 }
 
 
-/*! Creates a copy of the given BPath object.
+// Creates a copy of the given BPath object.
-	\param path the object to be copied
-*/
 BPath::BPath(const BPath& path)
 	:
 	fName(NULL),
@@ -51,10 +44,8 @@ BPath::BPath(const BPath& path)
 }
 
 
-/*!	\brief Creates a BPath object and initializes it to the filesystem entry
+// Creates a BPath object and initializes it to the filesystem entry
-	specified by the given entry_ref struct.
+// specified by the passed in entry_ref struct.
-	\param ref the entry_ref
-*/
 BPath::BPath(const entry_ref* ref)
 	:
 	fName(NULL),
@@ -64,10 +55,8 @@ BPath::BPath(const entry_ref* ref)
 }
 
 
-/*!	\brief Creates a BPath object and initializes it to the filesystem entry
+// Creates a BPath object and initializes it to the filesystem entry
-	specified by the given BEntry object.
+// specified by the passed in BEntry object.
-	\param entry the BEntry object
-*/
 BPath::BPath(const BEntry* entry)
 	:
 	fName(NULL),
@@ -77,17 +66,8 @@ BPath::BPath(const BEntry* entry)
 }
 
 
-/*! \brief Creates a BPath object and initializes it to the specified path or
+// Creates a BPath object and initializes it to the specified path or
-		   path and filename combination.
+// path and filename combination.
-
-	\param dir The base component of the pathname. May be absolute or relative.
-		   If relative, it is reckoned off the current working directory.
-	\param leaf The (optional) leaf component of the pathname. Must be
-		   relative. The value of leaf is concatenated to the end of \a dir
-		   (a "/" will be added as a separator, if necessary).
-	\param normalize boolean flag used to force normalization; normalization
-		   may occur even if false (see \ref _MustNormalize).
-*/
 BPath::BPath(const char* dir, const char* leaf, bool normalize)
 	:
 	fName(NULL),
@@ -97,16 +77,8 @@ BPath::BPath(const char* dir, const char* leaf, bool normalize)
 }
 
 
-/*! \brief Creates a BPath object and initializes it to the specified directory
+// Creates a BPath object and initializes it to the specified directory
-	 and filename combination.
+// and filename combination.
-	\param dir Refers to the directory that provides the base component of the
-		   pathname.
-	\param leaf The (optional) leaf component of the pathname. Must be
-		   relative. The value of leaf is concatenated to the end of \a dir
-		   (a "/" will be added as a separator, if necessary).
-	\param normalize boolean flag used to force normalization; normalization
-		   may occur even if false (see \ref _MustNormalize).
-*/
 BPath::BPath(const BDirectory* dir, const char* leaf, bool normalize)
 	:
 	fName(NULL),
@@ -116,17 +88,14 @@ BPath::BPath(const BDirectory* dir, const char* leaf, bool normalize)
 }
 
 
-//! Destroys the BPath object and frees any of its associated resources.
+// Destroys the BPath object and frees any of its associated resources.
 BPath::~BPath()
 {
 	Unset();
 }
 
 
-/*! \brief Returns the status of the most recent construction or SetTo() call.
+// Checks whether or not the object was properly initialized.
-	\return \c B_OK, if the BPath object is properly initialized, an error
-			code otherwise.
-*/
 status_t
 BPath::InitCheck() const
 {
@@ -134,15 +103,8 @@ BPath::InitCheck() const
 }
 
 
-/*! \brief Reinitializes the object to the filesystem entry specified by the
+// Reinitializes the object to the filesystem entry specified by the
-	given entry_ref struct.
+// passed in entry_ref struct.
-	\param ref the entry_ref
-	\return
-	- \c B_OK: The initialization was successful.
-	- \c B_BAD_VALUE: \c NULL \a ref.
-	- \c B_NAME_TOO_LONG: The pathname is longer than \c B_PATH_NAME_LENGTH.
-	- other error codes.
-*/
 status_t
 BPath::SetTo(const entry_ref* ref)
 {
@@ -162,14 +124,7 @@ BPath::SetTo(const entry_ref* ref)
 }
 
 
-/*! \brief Reinitializes the object to the specified filesystem entry.
+// Reinitializes the object to the specified filesystem entry.
-	\param entry the BEntry
-	\return
-	- \c B_OK: The initialization was successful.
-	- \c B_BAD_VALUE: \c NULL \a entry.
-	- \c B_NAME_TOO_LONG: The pathname is longer than \c B_PATH_NAME_LENGTH.
-	- other error codes.
-*/
 status_t
 BPath::SetTo(const BEntry* entry)
 {
@@ -186,19 +141,8 @@ BPath::SetTo(const BEntry* entry)
 }
 
 
-/*!	\brief Reinitializes the object to the specified path or path and file
+// Reinitializes the object to the passed in path or path and
-	name combination.
+// leaf combination.
-	\param path the path name
-	\param leaf the leaf name (may be \c NULL)
-	\param normalize boolean flag used to force normalization; normalization
-		   may occur even if false (see \ref _MustNormalize).
-	\return
-	- \c B_OK: The initialization was successful.
-	- \c B_BAD_VALUE: \c NULL \a path or absolute \a leaf.
-	- \c B_NAME_TOO_LONG: The pathname is longer than \c B_PATH_NAME_LENGTH.
-	- other error codes.
-	\note \code path.SetTo(path.Path(), "new leaf") \endcode is safe.
-*/
 status_t
 BPath::SetTo(const char* path, const char* leaf, bool normalize)
 {
@@ -255,19 +199,7 @@ BPath::SetTo(const char* path, const char* leaf, bool normalize)
 }
 
 
-/*!	\brief Reinitializes the object to the specified directory and relative
+// Reinitializes the object to the passed in dir and relative path combination.
-	path combination.
-	\param dir Refers to the directory that provides the base component of the
-		   pathname.
-	\param path the relative path name (may be \c NULL)
-	\param normalize boolean flag used to force normalization; normalization
-		   may occur even if false (see \ref _MustNormalize).
-	\return
-	- \c B_OK: The initialization was successful.
-	- \c B_BAD_VALUE: \c NULL \a dir or absolute \a path.
-	- \c B_NAME_TOO_LONG: The pathname is longer than \c B_PATH_NAME_LENGTH.
-	- other error codes.
-*/
 status_t
 BPath::SetTo(const BDirectory* dir, const char* path, bool normalize)
 {
@@ -289,9 +221,7 @@ BPath::SetTo(const BDirectory* dir, const char* path, bool normalize)
 }
 
 
-/*!	\brief Returns the object to an uninitialized state. The object frees any
+// Returns the object to an uninitialized state.
-	resources it allocated and marks itself as uninitialized.
-*/
 void
 BPath::Unset()
 {
@@ -300,18 +230,7 @@ BPath::Unset()
 }
 
 
-/*!	\brief Appends the given (relative) path to the end of the current path.
+// Appends the passed in relative path to the end of the current path.
-	This call fails if the path is absolute or the object to which you're
-	appending is uninitialized.
-	\param path relative pathname to append to current path (may be \c NULL).
-	\param normalize boolean flag used to force normalization; normalization
-		   may occur even if false (see \ref _MustNormalize).
-	\return
-	- \c B_OK: The initialization was successful.
-	- \c B_BAD_VALUE: The object is not properly initialized.
-	- \c B_NAME_TOO_LONG: The pathname is longer than \c B_PATH_NAME_LENGTH.
-	- other error codes.
-*/
 status_t
 BPath::Append(const char* path, bool normalize)
 {
@@ -325,11 +244,7 @@ BPath::Append(const char* path, bool normalize)
 }
 
 
-/*! \brief Returns the object's complete path name.
+// Gets the entire path of the object.
-	\return
-	- the object's path name, or
-	- \c NULL, if it is not properly initialized.
-*/
 const char*
 BPath::Path() const
 {
@@ -337,13 +252,7 @@ BPath::Path() const
 }
 
 
-/*! \brief Returns the leaf portion of the object's path name.
+// Gets the leaf portion of the path.
-	The leaf portion is defined as the string after the last \c '/'. For
-	the root path (\c "/") it is the empty string (\c "").
-	\return
-	- the leaf portion of the object's path name, or
-	- \c NULL, if it is not properly initialized.
-*/
 const char*
 BPath::Leaf() const
 {
@@ -362,17 +271,7 @@ BPath::Leaf() const
 }
 
 
-/*! \brief Calls the argument's SetTo() method with the name of the
+// Initializes path with the parent directory of the BPath object.
-	object's parent directory.
-	No normalization is done.
-	\param path the BPath object to be initialized to the parent directory's
-		   path name.
-	\return
-	- \c B_OK: Everything went fine.
-	- \c B_BAD_VALUE: \c NULL \a path.
-	- \c B_ENTRY_NOT_FOUND: The object represents \c "/".
-	- other error code returned by SetTo().
-*/
 status_t
 BPath::GetParent(BPath* path) const
 {
@@ -404,6 +303,7 @@ BPath::GetParent(BPath* path) const
 }
 
 
+// Gets whether or not the path is absolute or relative.
 bool
 BPath::IsAbsolute() const
 {
@@ -414,12 +314,7 @@ BPath::IsAbsolute() const
 }
 
 
-/*! \brief Performs a simple (string-wise) comparison of paths.
+// Performs a simple (string-wise) comparison of paths for equality.
-	No normalization takes place! Uninitialized BPath objects are considered
-	to be equal.
-	\param item the BPath object to be compared with
-	\return \c true, if the path names are equal, \c false otherwise.
-*/
 bool
 BPath::operator==(const BPath& item) const
 {
@@ -427,11 +322,7 @@ BPath::operator==(const BPath& item) const
 }
 
 
-/*! \brief Performs a simple (string-wise) comparison of paths.
+// Performs a simple (string-wise) comparison of paths for equality.
-	No normalization takes place!
-	\param path the path name to be compared with
-	\return \c true, if the path names are equal, \c false otherwise.
-*/
 bool
 BPath::operator==(const char* path) const
 {
@@ -440,12 +331,7 @@ BPath::operator==(const char* path) const
 }
 
 
-/*! \brief Performs a simple (string-wise) comparison of paths.
+// Performs a simple (string-wise) comparison of paths for inequality.
-	No normalization takes place! Uninitialized BPath objects are considered
-	to be equal.
-	\param item the BPath object to be compared with
-	\return \c true, if the path names are not equal, \c false otherwise.
-*/
 bool
 BPath::operator!=(const BPath& item) const
 {
@@ -453,11 +339,7 @@ BPath::operator!=(const BPath& item) const
 }
 
 
-/*! \brief Performs a simple (string-wise) comparison of paths.
+// Performs a simple (string-wise) comparison of paths for inequality.
-	No normalization takes place!
-	\param path the path name to be compared with
-	\return \c true, if the path names are not equal, \c false otherwise.
-*/
 bool
 BPath::operator!=(const char* path) const
 {
@@ -465,10 +347,7 @@ BPath::operator!=(const char* path) const
 }
 
 
-/*! \brief Initializes the object to be a copy of the argument.
+// Initializes the object as a copy of item.
-	\param item the BPath object to be copied
-	\return \c *this
-*/
 BPath&
 BPath::operator=(const BPath& item)
 {
@@ -478,11 +357,7 @@ BPath::operator=(const BPath& item)
 }
 
 
-/*! \brief Initializes the object to be a copy of the argument.
+// Initializes the object with the passed in path.
-	Has the same effect as \code SetTo(path) \endcode.
-	\param path the path name to be assigned to this object
-	\return \c *this
-*/
 BPath&
 BPath::operator=(const char* path)
 {
@@ -509,10 +384,7 @@ static const size_t flattened_entry_ref_size
 	= sizeof(dev_t) + sizeof(ino_t);
 
 
-/*! \brief Returns \c false.
+// Overrides BFlattenable::IsFixedSize()
-	Implements BFlattenable.
-	\return \c false
-*/
 bool
 BPath::IsFixedSize() const
 {
@@ -520,10 +392,7 @@ BPath::IsFixedSize() const
 }
 
 
-/*! \brief Returns \c B_REF_TYPE.
+// Overrides BFlattenable::TypeCode()
-	Implements BFlattenable.
-	\return \c B_REF_TYPE
-*/
 type_code
 BPath::TypeCode() const
 {
@@ -531,11 +400,8 @@ BPath::TypeCode() const
 }
 
 
-/*!	\brief Returns the size of the flattened entry_ref structure that
+// Gets the size of the flattened entry_ref struct that represents
-	represents the pathname.
+// the path in bytes.
-	Implements BFlattenable.
-	\return the size needed for flattening.
-*/
 ssize_t
 BPath::FlattenedSize() const
 {
@@ -551,23 +417,14 @@ BPath::FlattenedSize() const
 }
 
 
-/*!	\brief Converts the object's pathname to an entry_ref and writes it into
+// Converts the path of the object to an entry_ref and writes it into buffer.
-	buffer.
-	Implements BFlattenable.
-	\param buffer the buffer the data shall be stored in
-	\param size the size of \a buffer
-	\return
-	- \c B_OK: Everything went fine.
-	- \c B_BAD_VALUE: \c NULL buffer or the buffer is of insufficient size.
-	- other error codes.
-	\todo Reimplement for performance reasons: Don't call FlattenedSize().
-*/
 status_t
 BPath::Flatten(void* buffer, ssize_t size) const
 {
 	if (buffer == NULL)
 		return B_BAD_VALUE;
 
+	// ToDo: Re-implement for performance reasons: Don't call FlattenedSize().
 	ssize_t flattenedSize = FlattenedSize();
 	if (flattenedSize < 0)
 		return flattenedSize;
@@ -597,11 +454,7 @@ BPath::Flatten(void* buffer, ssize_t size) const
 }
 
 
-/*! \brief Returns \c true if code is \c B_REF_TYPE, and false otherwise.
+// Checks if type code is equal to B_REF_TYPE.
-	Implements BFlattenable.
-	\param code the type code in question
-	\return \c true if code is \c B_REF_TYPE, and false otherwise.
-*/
 bool
 BPath::AllowsTypeCode(type_code code) const
 {
@@ -609,19 +462,8 @@ BPath::AllowsTypeCode(type_code code) const
 }
 
 
-/*!	\brief Initializes the BPath with the flattened entry_ref data that's
+// Initializes the object with the flattened entry_ref data from the passed
-	found in the supplied buffer.
+// in buffer.
-	The type code must be \c B_REF_TYPE.
-	Implements BFlattenable.
-	\param code the type code of the flattened data
-	\param buf a pointer to the flattened data
-	\param size the number of bytes contained in \a buf
-	\return
-	- \c B_OK: Everything went fine.
-	- \c B_BAD_VALUE: \c NULL buffer or the buffer doesn't contain an
-	  entry_ref.
-	- other error codes.
-*/
 status_t
 BPath::Unflatten(type_code code, const void* buffer, ssize_t size)
 {
@@ -655,14 +497,7 @@ void BPath::_WarPath2() {}
 void BPath::_WarPath3() {}
 
 
-/*!	\brief Sets the supplied path.
+// Sets the supplied path.
-	The path is copied. If \c NULL, the object's path is set to NULL as well.
-	The object's old path is deleted.
-	\param path the path to be set
-	\return
-	- \c B_OK: Everything went fine.
-	- \c B_NO_MEMORY: Insufficient memory.
-*/
 status_t
 BPath::_SetPath(const char* path)
 {
@@ -684,20 +519,7 @@ BPath::_SetPath(const char* path)
 }
 
 
-/*! \brief Checks a path to see if normalization is required.
+// Checks a path to see if normalization is required.
-
-	The following items require normalization:
-		- Relative pathnames (after concatenation; e.g. "boot/ltj")
-		- The presence of "." or ".." ("/boot/ltj/../ltj/./gwar")
-		- Redundant slashes ("/boot//ltj")
-		- A trailing slash ("/boot/ltj/")
-
-	\param _error A pointer to an error variable that will be set if the input
-		is not a valid path.
-	\return
-		- \c true: \a path requires normalization
-		- \c false: \a path does not require normalization
-*/
 bool
 BPath::_MustNormalize(const char* path, status_t* _error)
 {
@@ -773,14 +595,3 @@ BPath::_MustNormalize(const char* path, status_t* _error)
 		return false;
 	}
 }
-
-
-/*!
-	\var char *BPath::fName
-	\brief Pointer to the object's path name string.
-*/
-
-/*!
-	\var status_t BPath::fCStatus
-	\brief The object's initialization status.
-*/