[haiku-commits] haiku: hrev45261 - docs/user/storage src/kits/storage
- From: jscipione@xxxxxxxxx
- To: haiku-commits@xxxxxxxxxxxxx
- Date: Sat, 9 Feb 2013 06:44:29 +0100 (CET)
hrev45261 adds 1 changeset to branch 'master'
old head: b3252dc18a923eeb3bb3ee738c41904cc0260a4e
new head: 4c064a84514683bd3d11442e26b5e8d2fbf784a6
overview: http://cgit.haiku-os.org/haiku/log/?qt=range&q=4c064a8+%5Eb3252dc
----------------------------------------------------------------------------
4c064a8: 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.
[ John Scipione <jscipione@xxxxxxxxx> ]
----------------------------------------------------------------------------
Revision: hrev45261
Commit: 4c064a84514683bd3d11442e26b5e8d2fbf784a6
URL: http://cgit.haiku-os.org/haiku/commit/?id=4c064a8
Author: John Scipione <jscipione@xxxxxxxxx>
Date: Sat Feb 9 05:39:53 2013 UTC
----------------------------------------------------------------------------
3 files changed, 547 insertions(+), 231 deletions(-)
docs/user/storage/Path.dox | 503 +++++++++++++++++++++++++++++++++++++++++
headers/os/storage/Path.h | 2 +
src/kits/storage/Path.cpp | 273 ++++------------------
----------------------------------------------------------------------------
diff --git a/docs/user/storage/Path.dox b/docs/user/storage/Path.dox
new file mode 100644
index 0000000..f087985
--- /dev/null
+++ b/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, axeld@xxxxxxxxxxxxxxxx
+ * John Scipione, jscipione@xxxxxxxxx
+ * Ingo Weinhold, bonefish@xxxxxxxxxxxx
+ *
+ * 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.
+*/
diff --git a/headers/os/storage/Path.h b/headers/os/storage/Path.h
index d12723a..80e15ef 100644
--- a/headers/os/storage/Path.h
+++ b/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
diff --git a/src/kits/storage/Path.cpp b/src/kits/storage/Path.cpp
index 7c61299..442462a 100644
--- a/src/kits/storage/Path.cpp
+++ b/src/kits/storage/Path.cpp
@@ -4,16 +4,11 @@
*
* Authors:
* Tyler Dauwalder
+ * Axel Dörfler, axeld@xxxxxxxxxxxxxxxx
* Ingo Weinhold, bonefish@xxxxxxxxxxxx
*/
-/*!
- \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.
- \param path the object to be copied
-*/
+// Creates a copy of the given BPath object.
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
- specified by the given entry_ref struct.
- \param ref the entry_ref
-*/
+// Creates a BPath object and initializes it to the filesystem entry
+// specified by the passed in entry_ref struct.
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
- specified by the given BEntry object.
- \param entry the BEntry object
-*/
+// Creates a BPath object and initializes it to the filesystem entry
+// specified by the passed in 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
- 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).
-*/
+// Creates a BPath object and initializes it to the specified path or
+// path and filename combination.
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
- 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).
-*/
+// Creates a BPath object and initializes it to the specified directory
+// and filename combination.
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.
- \return \c B_OK, if the BPath object is properly initialized, an error
- code otherwise.
-*/
+// Checks whether or not the object was properly initialized.
status_t
BPath::InitCheck() const
{
@@ -134,15 +103,8 @@ BPath::InitCheck() const
}
-/*! \brief Reinitializes the object to the filesystem entry specified by the
- given 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.
-*/
+// Reinitializes the object to the filesystem entry specified by the
+// passed in entry_ref struct.
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.
- \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.
-*/
+// Reinitializes the object to the specified filesystem entry.
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
- name 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.
-*/
+// Reinitializes the object to the passed in path or path and
+// leaf combination.
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
- 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.
-*/
+// Reinitializes the object to the passed in dir and relative path combination.
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
- resources it allocated and marks itself as uninitialized.
-*/
+// Returns the object to an uninitialized state.
void
BPath::Unset()
{
@@ -300,18 +230,7 @@ BPath::Unset()
}
-/*! \brief Appends the given (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.
-*/
+// Appends the passed in relative path to the end of the current path.
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.
- \return
- - the object's path name, or
- - \c NULL, if it is not properly initialized.
-*/
+// Gets the entire path of the object.
const char*
BPath::Path() const
{
@@ -337,13 +252,7 @@ BPath::Path() const
}
-/*! \brief Returns the leaf portion of the object's path name.
- 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.
-*/
+// Gets the leaf portion of the path.
const char*
BPath::Leaf() const
{
@@ -362,17 +271,7 @@ BPath::Leaf() const
}
-/*! \brief Calls the argument's SetTo() method with the name of the
- 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().
-*/
+// Initializes path with the parent directory of the BPath object.
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.
- 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.
-*/
+// Performs a simple (string-wise) comparison of paths for equality.
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.
- 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.
-*/
+// Performs a simple (string-wise) comparison of paths for equality.
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.
- 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.
-*/
+// Performs a simple (string-wise) comparison of paths for inequality.
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.
- 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.
-*/
+// Performs a simple (string-wise) comparison of paths for inequality.
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.
- \param item the BPath object to be copied
- \return \c *this
-*/
+// Initializes the object as a copy of item.
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.
- Has the same effect as \code SetTo(path) \endcode.
- \param path the path name to be assigned to this object
- \return \c *this
-*/
+// Initializes the object with the passed in path.
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.
- Implements BFlattenable.
- \return \c false
-*/
+// Overrides BFlattenable::IsFixedSize()
bool
BPath::IsFixedSize() const
{
@@ -520,10 +392,7 @@ BPath::IsFixedSize() const
}
-/*! \brief Returns \c B_REF_TYPE.
- Implements BFlattenable.
- \return \c B_REF_TYPE
-*/
+// Overrides BFlattenable::TypeCode()
type_code
BPath::TypeCode() const
{
@@ -531,11 +400,8 @@ BPath::TypeCode() const
}
-/*! \brief Returns the size of the flattened entry_ref structure that
- represents the pathname.
- Implements BFlattenable.
- \return the size needed for flattening.
-*/
+// Gets the size of the flattened entry_ref struct that represents
+// the path in bytes.
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
- 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().
-*/
+// Converts the path of the object to an entry_ref and writes it into buffer.
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.
- Implements BFlattenable.
- \param code the type code in question
- \return \c true if code is \c B_REF_TYPE, and false otherwise.
-*/
+// Checks if type code is equal to B_REF_TYPE.
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
- found in the supplied 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.
-*/
+// Initializes the object with the flattened entry_ref data from the passed
+// in buffer.
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.
- 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.
-*/
+// Sets the supplied path.
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.
-
- 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
-*/
+// Checks a path to see if normalization is required.
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.
-*/
Other related posts:
- » [haiku-commits] haiku: hrev45261 - docs/user/storage src/kits/storage - jscipione
