Documentation updates for Storage Kit classes

* Added \since to each method and parameter.
* Whitespace cleanup.
* Some other minor cleanups and updates.

docs/user/storage/AppFileInfo.dox

@@ -1,5 +1,5 @@
 /*
- * Copyright 2011 Haiku, Inc. All rights reserved.
+ * Copyright 2011-2014 Haiku, Inc. All rights reserved.
  * Distributed under the terms of the MIT License.
  *
  * Authors:
@@ -7,8 +7,8 @@
  *		Ingo Weinhold, [email protected]
  *
  * Corresponds to:
- *		headers/os/storage/AppFileInfo.h	 rev 42274
+ *		headers/os/storage/AppFileInfo.h	 hrev47402
- *		src/kits/storage/AppFileInfo.cpp	 rev 42274
+ *		src/kits/storage/AppFileInfo.cpp	 hrev47402
  */
 
 
@@ -46,19 +46,23 @@
 	object will next look at the resource of the BFile. You can tell the
 	BFileInfo object to look only in the attributes or resources with the
 	SetInfoLocation() method.
+
+	\since BeOS R3
 */
 
 
 /*!
 	\fn BAppFileInfo::BAppFileInfo()
 	\brief Creates an uninitialized BAppFileInfo object.
+
+	\since BeOS R3
 */
 
 
 /*!
 	\fn BAppFileInfo::BAppFileInfo(BFile* file)
 	\brief Creates an BAppFileInfo object and initializes it to the supplied
-		file.
+	       file.
 
 	The caller retains ownership of the supplied BFile object. It must not
 	be deleted during the life time of the BAppFileInfo. It is not deleted
@@ -66,6 +70,8 @@
 
 	\param file The BFile object that the BAppFileInfo object shall be
 		initialized to.
+
+	\since BeOS R3
 */
 
 
@@ -74,6 +80,8 @@
 	\brief Frees all resources associated with this object.
 
 	The supplied BFile object is not deleted if one is specified.
+
+	\since BeOS R3
 */
 
 
@@ -91,6 +99,8 @@
 	\returns an status code.
 	\retval B_OK Everything went fine.
 	\retval B_BAD_VALUE \c NULL \a file or \a file is not properly initialized.
+
+	\since BeOS R3
 */
 
 
@@ -107,17 +117,19 @@
 	\brief Gets the MIME type of the associated file.
 
 	\param type A pointer to a pre-allocated character buffer of size
-		   \c B_MIME_TYPE_LENGTH or larger into which the MIME type of the
+	       \c B_MIME_TYPE_LENGTH or larger into which the MIME type of the
-		   file will be written.
+	       file will be written.
 
 	\returns A status code.
 	\retval B_OK Everything went fine.
 	\retval B_NO_INIT The object is not properly initialized.
 	\retval B_BAD_VALUE \c NULL \a type or the type string stored in the
-		attribute/resources is longer than \c B_MIME_TYPE_LENGTH.
+	        attribute/resources is longer than \c B_MIME_TYPE_LENGTH.
 	\retval B_BAD_TYPE The attribute/resources the type string is stored in
-		has the wrong type.
+	        has the wrong type.
 	\retval B_ENTRY_NOT_FOUND No type is set on the file.
+
+	\since BeOS R3
 */
 
 
@@ -128,13 +140,15 @@
 	If \a type is \c NULL if the file's MIME type is unset.
 
 	\param type The MIME type to be assigned to the file. It must not be
-		longer than \c B_MIME_TYPE_LENGTH (including the terminating null).
+	       longer than \c B_MIME_TYPE_LENGTH (including the terminating \0).
-		The MIME type may be \c NULL.
+	       The MIME type may be \c NULL.
 
 	\returns a status code.
 	\retval B_OK Everything went fine.
 	\retval B_NO_INIT The object is not properly initialized.
 	\retval B_BAD_VALUE \a type is longer than \c B_MIME_TYPE_LENGTH.
+
+	\since BeOS R3
 */
 
 
@@ -154,17 +168,19 @@
 	\brief Gets the application signature of the associated file.
 
 	\param signature A pointer to a pre-allocated character buffer of size
-		   \c B_MIME_TYPE_LENGTH or larger into which the application
+	       \c B_MIME_TYPE_LENGTH or larger into which the application
-		   signature of the file will be written.
+	       signature of the file will be written.
 
 	\returns a status code.
 	\retval B_OK Everything went fine.
 	\retval B_NO_INIT The object is not properly initialized.
 	\retval B_BAD_VALUE \c NULL \a signature or the signature stored in the
-		attribute/resources is longer than \c B_MIME_TYPE_LENGTH.
+	        attribute/resources is longer than \c B_MIME_TYPE_LENGTH.
 	\retval B_BAD_TYPE The attribute/resources the signature is stored in have
-		the wrong type.
+	        the wrong type.
 	\retval B_ENTRY_NOT_FOUND No signature is set on the file.
+
+	\since BeOS R3
 */
 
 
@@ -175,13 +191,15 @@
 	If \a signature is \c NULL the file's application signature is unset.
 
 	\param signature The application signature to be assigned to the file.
-		Must not be longer than \c B_MIME_TYPE_LENGTH (including the
+	       Must not be longer than \c B_MIME_TYPE_LENGTH (including the
-		terminating \c NUL). The \a signature may be \c NULL.
+	       terminating \0). The \a signature may be \c NULL.
 
 	\returns a status code.
 	\retval B_OK Everything went fine.
 	\retval B_NO_INIT The object is not properly initialized.
 	\retval B_BAD_VALUE \a signature is longer than \c B_MIME_TYPE_LENGTH.
+
+	\since BeOS R3
 */
 
 
@@ -201,17 +219,19 @@
 	\brief Gets the catalog entry of the associated file used for localization.
 
 	\param catalogEntry A pointer to a pre-allocated character buffer of size
-		   \c B_MIME_TYPE_LENGTH * 3 or larger into which the catalog entry
+	       \c B_MIME_TYPE_LENGTH * 3 or larger into which the catalog entry
-		   of the file will be written.
+	       of the file will be written.
 
 	\returns a status code.
 	\retval B_OK Everything went fine.
 	\retval B_NO_INIT The object is not properly initialized.
 	\retval B_BAD_VALUE \c NULL \a catalogEntry or the entry stored in the
-		attribute/resources is longer than \c B_MIME_TYPE_LENGTH * 3.
+	        attribute/resources is longer than \c B_MIME_TYPE_LENGTH * 3.
 	\retval B_BAD_TYPE The attribute/resources the entry is stored in have
-		the wrong type.
+	        the wrong type.
 	\retval B_ENTRY_NOT_FOUND No catalog entry is set on the file.
+
+	\since Haiku R1
 */
 
 
@@ -222,15 +242,17 @@
 	If \a catalogEntry is \c NULL the file's catalog entry is unset.
 
 	\param catalogEntry The catalog entry to be assigned to the file.
-		Of the form "x-vnd.Haiku-app:context:name". Must not be longer than
+	       Of the form "x-vnd.Haiku-app:context:name". Must not be longer than
-		\c B_MIME_TYPE_LENGTH * 3 (including the terminating \c NUL).
+	       \c B_MIME_TYPE_LENGTH * 3 (including the terminating \0).
-		The \a catalogEntry may be \c NULL.
+	       The \a catalogEntry may be \c NULL.
 
 	\returns a status code.
 	\retval B_OK Everything went fine.
 	\retval B_NO_INIT The object is not properly initialized.
 	\retval B_BAD_VALUE \a catalogEntry is longer than
-		\c B_MIME_TYPE_LENGTH * 3.
+	        \c B_MIME_TYPE_LENGTH * 3.
+
+	\since Haiku R1
 */
 
 
@@ -250,15 +272,17 @@
 	\brief Gets the application \a flags of the associated file.
 
 	\param flags A pointer to a pre-allocated \c uint32 into which the
-		application flags of the file are written.
+	       application flags of the file are written.
 
 	\returns A status code.
 	\retval B_OK Everything went fine.
 	\retval B_NO_INIT The object is not properly initialized.
 	\retval B_BAD_VALUE \c NULL \a flags.
 	\retval B_BAD_TYPE The attribute/resources the flags are stored in have
-		the wrong type.
+	        the wrong type.
 	\retval B_ENTRY_NOT_FOUND No application flags are set on the file.
+
+	\since BeOS R3
 */
 
 
@@ -271,6 +295,8 @@
 	\returns A status code.
 	\retval B_OK Everything went fine.
 	\retval B_NO_INIT The object was not properly initialized.
+
+	\since BeOS R3
 */
 
 
@@ -281,6 +307,8 @@
 	\returns A status code.
 	\retval B_OK Everything went fine.
 	\retval B_NO_INIT The object was not properly initialized.
+
+	\since Haiku R1
 */
 
 
@@ -303,24 +331,26 @@
 	\c B_STRING_TYPE in \a types.
 
 	\param types A pointer to a pre-allocated BMessage into which the
-		MIME types supported by the application will be written.
+	       MIME types supported by the application will be written.
 
 	\returns A status code.
 	\retval B_OK Everything went fine.
 	\retval B_NO_INIT The object is not properly initialized.
 	\retval B_BAD_VALUE \c NULL \a types.
 	\retval B_BAD_TYPE The attribute/resources that the supported types
-		are stored in have the wrong type.
+	        are stored in have the wrong type.
 	\retval B_ENTRY_NOT_FOUND No supported types are set on the file.
+
+	\since BeOS R3
 */
 
 
 /*!
 	\fn status_t BAppFileInfo::SetSupportedTypes(const BMessage* types,
 		bool updateMimeDB, bool syncAll)
-	\brief Sets the MIME types that are supported by the application and allows
+	\brief Sets the MIME types that are supported by the application
-		you to specify whether or not the supported types in the MIME DB shall
+	       and allows you to specify whether or not the supported types
-		be updated as well.
+	       in the MIME DB shall be updated as well.
 
 	If \a types is \c NULL then the application's supported types are unset.
 
@@ -338,15 +368,17 @@
 	is \c true.
 
 	\param types The supported types to be assigned to the file.
-		May be \c NULL.
+	       May be \c NULL.
 	\param updateMimeDB \c true to update the supported types in the MIME DB,
-		\c false otherwise.
+	       \c false otherwise.
 	\param syncAll \c true to also synchronize the no-longer supported
-		types, \c false otherwise.
+	       types, \c false otherwise.
 
 	\returns A status code.
 	\retval B_OK Everything went fine.
 	\retval B_NO_INIT The object is not properly initialized.
+
+	\since BeOS R3
 */
 
 
@@ -354,8 +386,8 @@
 	\fn status_t BAppFileInfo::SetSupportedTypes(const BMessage* types,
 		bool syncAll)
 	\brief Sets the MIME types that are supported by the application and allows
-		you to specify whether or not the no longer supported types shall be
+	       you to specify whether or not the no longer supported types shall be
-		updated as well.
+	       updated as well.
 
 	If \a types is \c NULL then the application's supported types are unset.
 
@@ -372,13 +404,15 @@
 	from the list of supporting applications.
 
 	\param types The supported types to be assigned to the file.
-		May be \c NULL.
+	       May be \c NULL.
 	\param syncAll \c true to also synchronize the no-longer supported
-		types, \c false otherwise.
+	       types, \c false otherwise.
 
 	\returns A status code.
 	\retval B_OK Everything went fine.
 	\retval B_NO_INIT The object is not properly initialized.
+
+	\since BeOS R3
 */
 
 
@@ -390,10 +424,12 @@
 	\see SetSupportedType(const BMessage*, bool) for detailed information.
 
 	\param types The supported types to be assigned to the file.
-		May be \c NULL.
+	       May be \c NULL.
 	\returns A status code.
 	\retval B_OK Everything went fine.
 	\retval B_NO_INIT The object is not properly initialized.
+
+	\since BeOS R3
 */
 
 
@@ -408,6 +444,8 @@
 
 	\returns \c true if \a type is a valid MIME type and it is supported by
 		the application, \c false otherwise.
+
+	\since BeOS R3
 */
 
 
@@ -424,6 +462,8 @@
 
 	\returns \c true if \a type is a valid MIME type and it is explicitly
 		supported by the application, \c false otherwise.
+
+	\since BeOS R3
 */
 
 
@@ -440,21 +480,23 @@
 
 /*!
 	\fn status_t BAppFileInfo::GetIcon(BBitmap* icon, icon_size which) const
-	\brief Gets the icon of the associated file and puts it into a pre-allocated
+	\brief Gets the icon of the associated file and puts it into a
-		   BBitmap.
+	       pre-allocated BBitmap.
 
 	\param icon A pointer to a pre-allocated BBitmap of the correct dimension
-		to store the requested icon (16x16 for the \c B_MINI_ICON and 32x32
+	       to store the requested icon (16x16 for the \c B_MINI_ICON and 32x32
-		for the \c B_LARGE_ICON).
+	       for the \c B_LARGE_ICON).
 	\param which Specifies the size of the icon to be retrieved:
-		\c B_MINI_ICON for the mini and \c B_LARGE_ICON for the large icon.
+	       \c B_MINI_ICON for the mini and \c B_LARGE_ICON for the large icon.
-		For HVIF icons this parameter has no effect.
+	       For HVIF icons this parameter has no effect.
 
 	\returns A status code.
 	\retval B_OK Everything went fine.
 	\retval B_NO_INIT The object is not properly initialized.
 	\retval B_BAD_VALUE \c NULL \a icon, unsupported icon size \a which or
-		bitmap dimensions (\a icon) and icon size (\a which) do not match.
+	        bitmap dimensions (\a icon) and icon size (\a which) do not match.
+
+	\since BeOS R3
 */
 
 
@@ -464,12 +506,14 @@
 
 	\param data The pointer in which the flat icon data will be returned.
 	\param size The pointer in which the size of the data found will be
-		returned.
+	       returned.
 
 	\returns A status code.
 	\retval B_OK Everything went fine.
 	\retval B_NO_INIT The object is not properly initialized.
 	\retval B_BAD_VALUE \c NULL \a data or \c NULL size.
+
+	\since BeOS R3
 */
 
 
@@ -481,20 +525,23 @@
 	If \a icon is \c NULL then the icon of the file is unset.
 
 	\param icon A pointer to the BBitmap containing the icon to be set.
-		May be \c NULL to specify no icon.
+	       May be \c NULL to specify no icon.
 	\param which Specifies the size of the icon to be set: \c B_MINI_ICON for
-		16x16 mini icon and \c B_LARGE_ICON for the 32x32 large icon.
+	       16x16 mini icon and \c B_LARGE_ICON for the 32x32 large icon.
-		For HVIF icons this parameter has no effect.
+	       For HVIF icons this parameter has no effect.
 	\param updateMimeDB \c true to also set the icon for the application in the
-		MIME DB. \c false otherwise.
+	       MIME DB. \c false otherwise.
 
 	\returns A status code.
 	\retval B_OK Everything went fine.
 	\retval B_NO_INIT The object is not properly initialized.
 	\retval B_BAD_VALUE Unknown icon size \a which or bitmap dimensions
-		(\a icon) and icon size (\a which) do not match.
+	        (\a icon) and icon size (\a which) do not match.
+
+	\since Haiku R1
 */
 
+
 /*!
 	\fn status_t BAppFileInfo::SetIcon(const BBitmap* icon, icon_size which)
 	\brief Sets the icon of the associated file from a BBitmap.
@@ -505,16 +552,18 @@
 	application signature.
 
 	\param icon A pointer to the BBitmap containing the icon to be set.
-		May be \c NULL to specify no icon.
+	       May be \c NULL to specify no icon.
 	\param which Specifies the size of the icon to be set: \c B_MINI_ICON for
-		16x16 mini icon and \c B_LARGE_ICON for the 32x32 large icon.
+	       16x16 mini icon and \c B_LARGE_ICON for the 32x32 large icon.
-		For HVIF icons this parameter has no effect.
+	       For HVIF icons this parameter has no effect.
 
 	\returns A status code.
 	\retval B_OK Everything went fine.
 	\retval B_NO_INIT The object is not properly initialized.
 	\retval B_BAD_VALUE Unknown icon size \a which or bitmap dimensions
-		(\a icon) and icon size (\a which) do not match.
+	        (\a icon) and icon size (\a which) do not match.
+
+	\since BeOS R3
 */
 
 
@@ -526,15 +575,17 @@
 	If \a data is \c NULL then the icon of the file is unset.
 
 	\param data A pointer to the data buffer containing the vector icon
-		   to be set. May be \c NULL.
+	       to be set. May be \c NULL.
 	\param size Specifies the size of buffer pointed to by \a data.
 	\param updateMimeDB \c true to also set the icon for the application in the
-		MIME DB. \c false otherwise.
+	       MIME DB. \c false otherwise.
 
 	\returns A status code.
 	\retval B_OK Everything went fine.
 	\retval B_NO_INIT The object is not properly initialized.
 	\retval B_BAD_VALUE \c NULL data.
+
+	\since Haiku R1
 */
 
 
@@ -548,13 +599,15 @@
 	application signature.
 
 	\param data A pointer to the data buffer containing the vector icon
-		   to be set. May be \c NULL.
+	       to be set. May be \c NULL.
 	\param size Specifies the size of buffer pointed to by \a data.
 
 	\returns A status code.
 	\retval B_OK Everything went fine.
 	\retval B_NO_INIT The object is not properly initialized.
 	\retval B_BAD_VALUE \c NULL data.
+
+	\since Haiku R1
 */
 
 
@@ -562,23 +615,25 @@
 	\fn status_t BAppFileInfo::GetIconForType(const char* type, BBitmap* icon,
 		icon_size size) const
 	\brief Gets the icon the application provides for a given MIME type and
-		puts it into a BBitmap.
+	       puts it into a BBitmap.
 
 	\note If \a type is \c NULL, the application's icon is retrieved.
 
 	\param type The MIME type in question. May be \c NULL.
 	\param icon A pointer to a pre-allocated BBitmap of the correct dimension
-		to store the requested icon (16x16 for the mini and 32x32 for the
+	       to store the requested icon (16x16 for the mini and 32x32 for the
-		large icon).
+	       large icon).
 	\param size Specifies the size of the icon to be retrieved:
-		\c B_MINI_ICON for the mini and \c B_LARGE_ICON for the large icon.
+	       \c B_MINI_ICON for the mini and \c B_LARGE_ICON for the large icon.
 
 	\returns A status code.
 	\retval B_OK Everything went fine.
 	\retval B_NO_INIT The object is not properly initialized.
 	\retval B_BAD_VALUE \c NULL \a icon, unsupported icon size
-		\a which or bitmap dimensions (\a icon) and icon size (\a which) do
+	        \a which or bitmap dimensions (\a icon) and icon size (\a which)
-		not match.
+	        do not match.
+
+	\since BeOS R3
 */
 
 
@@ -586,7 +641,7 @@
 	\fn status_t BAppFileInfo::GetIconForType(const char* type, uint8** data,
 		size_t* size) const
 	\brief Gets the icon the application provides for a given MIME type and
-		puts it into a buffer.
+	       puts it into a buffer.
 
 	\note If \a type is set to \c NULL the the application's icon is retrieved.
 
@@ -599,7 +654,9 @@
 	\retval B_OK Everything went fine.
 	\retval B_NO_INIT The object is not properly initialized.
 	\retval B_BAD_VALUE \c NULL \a data and/or \a size. Or the supplied
-		\a type is not a valid MIME type.
+	        \a type is not a valid MIME type.
+
+	\since Haiku R1
 */
 
 
@@ -607,7 +664,7 @@
 	\fn status_t BAppFileInfo::SetIconForType(const char* type,
 		const BBitmap* icon, icon_size which, bool updateMimeDB)
 	\brief Sets the icon the application provides for a given MIME type from a
-		BBitmap.
+	       BBitmap.
 
 	\note If \a type is \c NULL then the icon is set.
 	\note If \a icon is \c NULL then the icon is unset.
@@ -618,18 +675,20 @@
 
 	\param type The MIME type in question. May be \c NULL.
 	\param icon A pointer to the BBitmap containing the icon to be set.
-		May be \c NULL.
+	       May be \c NULL.
 	\param which Specifies the size of the icon to be set: \c B_MINI_ICON
-		for the mini and \c B_LARGE_ICON for the large icon.
+	       for the mini and \c B_LARGE_ICON for the large icon.
 	\param updateMimeDB \c true to also set the icon for the type in the MIME
-		DB. \c false otherwise.
+	       DB. \c false otherwise.
 
 	\returns A status code.
 	\retval B_OK Everything went fine.
 	\retval B_NO_INIT The object is not properly initialized.
 	\retval B_BAD_VALUE Either the icon size \a which is unknown,
-		the bitmap dimensions (\a icon) and icon size (\a which) do not
+	        the bitmap dimensions (\a icon) and icon size (\a which) do not
-		match, or the provided \a type is not a valid MIME type. 
+	        match, or the provided \a type is not a valid MIME type. 
+
+	\since Haiku R1
 */
 
 
@@ -637,7 +696,7 @@
 	\fn status_t BAppFileInfo::SetIconForType(const char* type,
 		const BBitmap* icon, icon_size which)
 	\brief Sets the icon the application provides for a given MIME type from a
-		BBitmap.
+	       BBitmap.
 
 	\note If \a type is \c NULL then the icon is set.
 	\note If \a icon is \c NULL then the icon is unset.
@@ -656,8 +715,10 @@
 	\retval B_OK Everything went fine.
 	\retval B_NO_INIT The object is not properly initialized.
 	\retval B_BAD_VALUE Either the icon size \a which is unknown,
-		the bitmap dimensions (\a icon) and icon size (\a which) do not
+	        the bitmap dimensions (\a icon) and icon size (\a which) do not
-		match, or the provided \a type is not a valid MIME type.
+	        match, or the provided \a type is not a valid MIME type.
+
+	\since BeOS R3
 */
 
 
@@ -665,7 +726,7 @@
 	\fn status_t BAppFileInfo::SetIconForType(const char* type,
 		const uint8* data, size_t size, bool updateMimeDB)
 	\brief Sets the icon the application provides for a given MIME type from a
-		buffer.
+	       buffer.
 
 	\note If \a type is \c NULL then the icon is set.
 	\note If \a data is \c NULL then the icon is unset.
@@ -676,15 +737,17 @@
 
 	\param type The MIME type in question. May be \c NULL.
 	\param data A pointer to the data containing the icon to be set.
-		   May be \c NULL.
+	       May be \c NULL.
 	\param size Specifies the size of buffer provided in \a data.
 	\param updateMimeDB \c true to also set the icon for the type in the MIME
-		DB. \c false otherwise.
+	       DB. \c false otherwise.
 
 	\returns A status code.
 	\retval B_OK Everything went fine.
 	\retval B_NO_INIT The object is not properly initialized.
 	\retval B_BAD_VALUE The provided \a type is not a valid MIME type.
+
+	\since Haiku R1
 */
 
 
@@ -692,7 +755,7 @@
 	\fn status_t BAppFileInfo::SetIconForType(const char* type,
 		const uint8* data, size_t size)
 	\brief Sets the icon the application provides for a given MIME type from a
-		buffer.
+	       buffer.
 
 	\note If \a type is \c NULL then the icon is set.
 	\note If \a data is \c NULL then the icon is unset.
@@ -703,13 +766,15 @@
 
 	\param type The MIME type in question. May be \c NULL.
 	\param data A pointer to the data containing the icon to be set.
-		   May be \c NULL.
+	       May be \c NULL.
 	\param size Specifies the size of buffer provided in \a data.
 
 	\returns A status code.
 	\retval B_OK Everything went fine.
 	\retval B_NO_INIT The object is not properly initialized.
 	\retval B_BAD_VALUE The provided \a type is not a valid MIME type.
+
+	\since Haiku R1
 */
 
 
@@ -740,6 +805,8 @@
 	\retval B_OK Everything went fine.
 	\retval B_NO_INIT The object is not properly initialized.
 	\retval B_BAD_VALUE \c NULL \a info.
+
+	\since BeOS R3
 */
 
 
@@ -759,6 +826,8 @@
 	\returns A status code.
 	\retval B_OK Everything went fine.
 	\retval B_NO_INIT The object is not properly initialized.
+
+	\since BeOS R3
 */
 
 
@@ -783,6 +852,8 @@
 		- \c B_USE_BOTH_LOCATIONS: Store the data in attributes and resources.
 
 	\param location The location where the metadata shall be stored.
+
+	\since BeOS R3
 */
 
 
@@ -793,6 +864,8 @@
 
 	\returns \c true if the metadata are (also) stored in the file's
 		attributes, \c false otherwise.
+
+	\since BeOS R3
 */
 
 
@@ -803,111 +876,9 @@
 
 	\returns \c true if the metadata are (also) stored in the file's
 		resources, \c false otherwise.
+
+	\since BeOS R3
 */
 
 
 //! @}
-
-
-/*!
-	\fn BAppFileInfo & BAppFileInfo::operator=(const BAppFileInfo &)
-	\brief Privatized assignment operator to prevent usage.
-*/
-
-
-/*!
-	\fn BAppFileInfo::BAppFileInfo(const BAppFileInfo &)
-	\brief Privatized copy constructor to prevent usage.
-*/
-
-
-/*!
-	\fn status_t BAppFileInfo::GetMetaMime(BMimeType* meta) const
-	\brief Initializes a BMimeType to the signature of the associated file.
-
-	\warning The parameter \a meta is not checked.
-
-	\param meta A pointer to a pre-allocated BMimeType that shall be
-		   initialized to the signature of the associated file.
-
-	\returns A status code.
-	\retval B_OK Everything went fine.
-	\retval B_BAD_VALUE \c NULL \a meta
-	\retval B_ENTRY_NOT_FOUND The file has not signature or the signature is
-			(not installed in the MIME database.) no valid MIME string.
-*/
-
-
-/*!
-	\fn status_t BAppFileInfo::_ReadData(const char* name, int32 id,
-		type_code type, void* buffer, size_t bufferSize,
-		size_t &bytesRead, void** allocatedBuffer) const
-	\brief Reads data from an attribute or resource.
-
-	\note The data is read from the location specified by \a fWhere.
-
-	\warning The object must be properly initialized. The parameters are
-		\b NOT checked.
-
-	\param name The name of the attribute/resource to be read.
-	\param id The resource ID of the resource to be read. It is ignored
-		   when < 0.
-	\param type The type of the attribute/resource to be read.
-	\param buffer A pre-allocated buffer for the data to be read.
-	\param bufferSize The size of the supplied buffer.
-	\param bytesRead A reference parameter, set to the number of bytes
-		   actually read.
-	\param allocatedBuffer If not \c NULL, the method allocates a buffer
-		   large enough too store the whole data and writes a pointer to it
-		   into this variable. If \c NULL, the supplied buffer is used.
-
-	\returns A status code.
-	\retval B_OK Everything went fine.
-	\retval B_ENTRY_NOT_FOUND The entry was not found.
-	\retval B_NO_MEMORY Ran out of memory allocating the buffer.
-	\retval B_BAD_VALUE \a type did not match.
-*/
-
-
-/*!
-	\fn status_t BAppFileInfo::_WriteData(const char* name, int32 id,
-		type_code type, const void* buffer, size_t bufferSize, bool findID)
-	\brief Writes data to an attribute or resource.
-
-	\note The data is written to the location(s) specified by \a fWhere.
-
-	\warning The object must be properly initialized. The parameters are
-		\b NOT checked.
-
-	\param name The name of the attribute/resource to be written.
-	\param id The resource ID of the resource to be written.
-	\param type The type of the attribute/resource to be written.
-	\param buffer A buffer containing the data to be written.
-	\param bufferSize The size of the supplied buffer.
-	\param findID If set to \c true use the ID that is already assigned to the
-		   \a name / \a type pair or take the first unused ID >= \a id.
-		   If \c false, \a id is used.
-
-	\returns A status code.
-	\retval B_OK Everything went fine.
-	\retval B_ERROR An error occurred while trying to write the data.
-*/
-
-
-/*!
-	\fn status_t BAppFileInfo::_RemoveData(const char* name, type_code type)
-	\brief Removes an attribute or resource.
-
-	\note The removal location is specified by \a fWhere.
-
-	\warning The object must be properly initialized. The parameters are
-		\b NOT checked.
-
-	\param name The name of the attribute/resource to be remove.
-	\param type The type of the attribute/resource to be removed.
-
-	\returns A status code.
-	\retval B_OK Everything went fine.
-	\retval B_NO_INIT Not using attributes and not using resources.
-	\retval B_ENTRY_NOT_FOUND The attribute or resource was not found.
-*/

docs/user/storage/Directory.dox

@@ -1,5 +1,5 @@
 /*
- * Copyright 2011 Haiku, Inc. All rights reserved.
+ * Copyright 2011-2014 Haiku, Inc. All rights reserved.
  * Distributed under the terms of the MIT License.
  *
  * Authors:
@@ -9,8 +9,8 @@
  *		John Scipione, [email protected]
  *
  * Corresponds to:
- *		headers/os/storage/Directory.h  hrev43528
+ *		headers/os/storage/Directory.h	hrev47402
- *		src/kits/storage/Directory.cpp  hrev43528
+ *		src/kits/storage/Directory.cpp	hrev47402
  */
 
 
@@ -27,12 +27,16 @@
 	\ingroup storage
 	\ingroup libbe
 	\brief A directory in the file system.
+
+	\since BeOS R3
 */
 
 
 /*!
 	\fn BDirectory::BDirectory()
 	\brief Creates an uninitialized BDirectory object.
+
+	\since BeOS R3
 */
 
 
@@ -41,52 +45,64 @@
 	\brief Creates a copy of the supplied BDirectory object.
 
 	\param dir The BDirectory object to be copied.
+
+	\since BeOS R3
 */
 
 
 /*!
 	\fn BDirectory::BDirectory(const entry_ref* ref)
 	\brief Creates a BDirectory and initializes it to the directory referred
-		to by the supplied entry_ref.
+	       to by the supplied entry_ref.
 
 	\param ref The entry_ref that refers to the directory.
+
+	\since BeOS R3
 */
 
 
 /*!
 	\fn BDirectory::BDirectory(const node_ref* nref)
 	\brief Creates a BDirectory and initializes it to the directory referred
-		to by the supplied node_ref.
+	       to by the supplied node_ref.
 
 	\param nref The node_ref that refers to the directory.
+
+	\since BeOS R3
 */
 
 
 /*!
 	\fn BDirectory::BDirectory(const BEntry* entry)
 	\brief Creates a BDirectory and initializes it to the directory referred
-		to by the supplied BEntry.
+	       to by the supplied BEntry.
 
 	\param entry The BEntry that refers to the directory.
+
+	\since BeOS R3
 */
 
 
 /*!
 	\fn BDirectory::BDirectory(const char* path)
 	\brief Creates a BDirectory and initializes it to the directory referred
-		to by the supplied \a path name.
+	       to by the supplied \a path name.
 
 	\param path The \a path name of the directory.
+
+	\since BeOS R3
 */
 
 
 /*!
 	\fn BDirectory::BDirectory(const BDirectory* dir, const char* path)
 	\brief Creates a BDirectory and initializes it to the directory referred
-		to by the supplied path name relative to the specified BDirectory.
+	       to by the supplied path name relative to the specified BDirectory.
 
 	\param dir The base BDirectory object.
 	\param path The \a path of the directory relative to \a dir
+
+	\since BeOS R3
 */
 
 
@@ -96,13 +112,15 @@
 
 	If the BDirectory is properly initialized, the directory's file descriptor
 	is closed.
+
+	\since BeOS R3
 */
 
 
 /*!
 	\fn status_t BDirectory::SetTo(const entry_ref* ref)
 	\brief Re-initializes the BDirectory to the directory referred to by the
-		supplied entry_ref.
+	       supplied entry_ref.
 
 	\param ref The entry_ref referring to the directory.
 
@@ -116,13 +134,15 @@
 	\retval B_BUSY A node was busy.
 	\retval B_FILE_ERROR A general file error.
 	\retval B_NO_MORE_FDS The application has run out of file descriptors.
+
+	\since BeOS R3
 */
 
 
 /*!
 	\fn status_t BDirectory::SetTo(const node_ref* nref)
 	\brief Re-initializes the BDirectory to the directory referred to by the
-		supplied node_ref.
+	       supplied node_ref.
 
 	\param nref The node_ref referring to the directory.
 
@@ -136,13 +156,15 @@
 	\retval B_BUSY A node was busy.
 	\retval B_FILE_ERROR A general file error.
 	\retval B_NO_MORE_FDS The application has run out of file descriptors.
+
+	\since BeOS R3
 */
 
 
 /*!
 	\fn status_t BDirectory::SetTo(const BEntry* entry)
 	\brief Re-initializes the BDirectory to the directory referred to by the
-		supplied BEntry.
+	       supplied BEntry.
 
 	\param entry The BEntry referring to the directory.
 
@@ -156,13 +178,15 @@
 	\retval B_BUSY A node was busy.
 	\retval B_FILE_ERROR A general file error.
 	\retval B_NO_MORE_FDS The application has run out of file descriptors.
+
+	\since BeOS R3
 */
 
 
 /*!
 	\fn status_t BDirectory::SetTo(const char* path)
 	\brief Re-initializes the BDirectory to the directory referred to by the
-		supplied path name.
+	       supplied path name.
 
 	\param path The directory's \a path name.
 
@@ -178,13 +202,15 @@
 	\retval B_FILE_ERROR A general file error.
 	\retval B_NO_MORE_FDS The application has run out of file descriptors.
 	\retval B_NOT_A_DIRECTORY \a path includes a non-directory.
+
+	\since BeOS R3
 */
 
 
 /*!
 	\fn status_t BDirectory::SetTo(const BDirectory* dir, const char* path)
 	\brief Re-initializes the BDirectory to the directory referred to by the
-		supplied path name relative to the specified BDirectory.
+	       supplied path name relative to the specified BDirectory.
 
 	\param dir The base directory.
 	\param path The directory path name relative to \a dir.
@@ -201,13 +227,15 @@
 	\retval B_FILE_ERROR A general file error.
 	\retval B_NO_MORE_FDS The application has run out of file descriptors.
 	\retval B_NOT_A_DIRECTORY \a path includes a non-directory.
+
+	\since BeOS R3
 */
 
 
 /*!
 	\fn status_t BDirectory::GetEntry(BEntry* entry) const
 	\brief Gets a BEntry object referring to the directory. If the
-		initialization of \a entry fails, it is Unset().
+	       initialization of \a entry fails, it is Unset().
 
 	\param entry A pointer to the \a entry that will refer to the directory.
 
@@ -221,6 +249,8 @@
 	\retval B_BUSY A node was busy.
 	\retval B_FILE_ERROR A general file error.
 	\retval B_NO_MORE_FDS The application has run out of file descriptors.
+
+	\since BeOS R3
 */
 
 
@@ -229,7 +259,9 @@
 	\brief Returns whether the directory is the root directory of a volume.
 
 	\returns \c true if the BDirectory is properly initialized and represents
-		a root directory of a volume, \c false otherwise.
+	         a root directory of a volume, \c false otherwise.
+
+	\since BeOS R3
 */
 
 
@@ -237,18 +269,18 @@
 	\fn status_t BDirectory::FindEntry(const char* path, BEntry* entry,
 		bool traverse) const
 	\brief Finds an entry referred to by a path relative to the directory
-		represented by this BDirectory.
+	       represented by this BDirectory.
 
 	\a path may represent an absolute path. If the BDirectory is not properly
 	initialized then the entry is relative to the current directory. If the
 	entry couldn't be found, \a entry is Unset().
 
 	\note The functionality of this method differs from
-		BEntry::SetTo(BDirectory *, const char *, bool) in that it doesn't
+	      BEntry::SetTo(BDirectory *, const char *, bool) in that it doesn't
-		require the entry to exist, whereas this method does.
+	      require the entry to exist, whereas this method does.
 
 	\param path The entry's \a path name. May be relative to this directory
-		or an absolute path.
+	       or an absolute path.
 	\param entry A pointer to a BEntry to be initialized with the found entry.
 	\param traverse Whether or not to follow a symbolic link.
 
@@ -266,69 +298,77 @@
 	\retval B_NOT_A_DIRECTORY \a path includes a non-directory.
 
 	\sa BEntry::SetTo(BDirectory *, const char *, bool)
+
+	\since BeOS R3
 */
 
 
 /*!
 	\fn bool BDirectory::Contains(const char* path, int32 nodeFlags) const
 	\brief Returns whether or not this directory or any of its subdirectories
-		at any level contain the entry referred to by the supplied path name.
+	       at any level contain the entry referred to by the supplied path
+	       name.
 
 	Only entries that match the node flavor specified by \a nodeFlags are
 	considered.
 
-	If the BDirectory is not properly initialized, the method returns \c false.
+	If the BDirectory is not properly initialized, the method returns
-	A non-absolute path is considered relative to the current directory.
+	\c false. A non-absolute path is considered relative to the current
+	directory.
 
-	\note R5's implementation always returns \c true given an absolute path
+	\note BeOS R5's implementation always returns \c true given an absolute
-		or an unitialized directory. This implementation is not compatible
+	      path or an initialized directory. This implementation is not
-		with that behavior. Instead it converts the path into a BEntry and
+	      compatible with that behavior. Instead it converts the path into
-		passes it to the other version of Contains().
+	      a BEntry and passes it to the other version of Contains().
 
 	\param path The entry's \a path name. May be relative to this directory
-		or may be an absolute \a path.
+	       or may be an absolute \a path.
 	\param nodeFlags Any of the following:
-		- \c B_FILE_NODE: The entry must be a file.
+	       - \c B_FILE_NODE: The entry must be a file.
-		- \c B_DIRECTORY_NODE: The entry must be a directory.
+	       - \c B_DIRECTORY_NODE: The entry must be a directory.
-		- \c B_SYMLINK_NODE: The entry must be a symbolic link.
+	       - \c B_SYMLINK_NODE: The entry must be a symbolic link.
-		- \c B_ANY_NODE: The entry may be of any kind.
+	       - \c B_ANY_NODE: The entry may be of any kind.
 
 	\returns \c true if the entry exists and its kind does match \a nodeFlags
-		and the BDirectory is properly initialized and does contain the entry
+	         and the BDirectory is properly initialized and does contain the
-		at any level, \c false otherwise.
+	         entry at any level, \c false otherwise.
+
+	\since BeOS R3
 */
 
 
 /*!
 	\fn bool BDirectory::Contains(const BEntry* entry, int32 nodeFlags) const
 	\brief Returns whether or not this directory or any of its subdirectories
-		at any level contain the entry referred to by the supplied BEntry.
+	       at any level contain the entry referred to by the supplied BEntry.
-	
+
 	Only entries that match the node flavor specified by \a nodeFlags are
 	considered.
 
 	\note If the paths are identical, this method returns \c true to stay
-		consistent with BeOS 5.
+	      consistent with BeOS 5.
 
 	\param entry a BEntry referring to the entry
 	\param nodeFlags Any of the following:
-		- \c B_FILE_NODE: The entry must be a file.
+	       - \c B_FILE_NODE: The entry must be a file.
-		- \c B_DIRECTORY_NODE: The entry must be a directory.
+	       - \c B_DIRECTORY_NODE: The entry must be a directory.
-		- \c B_SYMLINK_NODE: The entry must be a symbolic link.
+	       - \c B_SYMLINK_NODE: The entry must be a symbolic link.
-		- \c B_ANY_NODE: The entry may be of any kind.
+	       - \c B_ANY_NODE: The entry may be of any kind.
 
 	\returns \c true if the BDirectory is properly initialized and the
-		entry of the matching kind was found, \c false otherwise.
+	         entry of the matching kind was found, \c false otherwise.
+
+	\since BeOS R3
 */
 
 
 /*!
 	\fn status_t BDirectory::GetStatFor(const char* path, struct stat* st) const
 	\brief Returns the stat structure of the entry referred to by the supplied
-		path name.
+	       path name.
 
 	\param path The entry's path name. May be relative to this directory or
-		   absolute, or \c NULL to get the directories stat info.
+	       absolute, or \c NULL to get the directories stat info.
 	\param st A pointer to the stat structure to be filled in by this method.
 
 	\returns A status code.
@@ -343,6 +383,8 @@
 	\retval B_FILE_ERROR A general file error.
 	\retval B_NO_MORE_FDS The application has run out of file descriptors.
 	\retval B_NOT_A_DIRECTORY \a path includes a non-directory.
+
+	\since BeOS R3
 */
 
 
@@ -353,7 +395,7 @@
 	Unlike GetNextDirents() this method ignores "." and "..".
 
 	\note The iterator used by this method is the same one used by
-		GetNextRef(), GetNextDirents(), Rewind() and CountEntries().
+	      GetNextRef(), GetNextDirents(), Rewind() and CountEntries().
 
 	\param entry A pointer to a BEntry to be initialized to the found entry
 	\param traverse Specifies whether or not to follow a symbolic link.
@@ -368,6 +410,8 @@
 	\retval B_BUSY A node was busy.
 	\retval B_FILE_ERROR A general file error.
 	\retval B_NO_MORE_FDS The application has run out of file descriptors.
+
+	\since BeOS R3
 */
 
 
@@ -378,10 +422,10 @@
 	Unlike GetNextDirents() this method ignores "." and "..".
 
 	\note The iterator used be this method is the same one used by
-		GetNextEntry(), GetNextDirents(), Rewind() and CountEntries().
+	      GetNextEntry(), GetNextDirents(), Rewind() and CountEntries().
 
 	\param ref A pointer to an entry_ref to be filled in with the data
-		from the found entry.
+	       from the found entry.
 
 	\returns A status code.
 	\retval B_OK Everything went fine.
@@ -393,27 +437,31 @@
 	\retval B_BUSY A node was busy.
 	\retval B_FILE_ERROR A general file error.
 	\retval B_NO_MORE_FDS The application has run out of file descriptors.
+
+	\since BeOS R3
 */
 
 
 /*!
-	\fn int32 BDirectory::GetNextDirents(dirent* buf, size_t bufSize, int32 count)
+	\fn int32 BDirectory::GetNextDirents(dirent* buf, size_t bufSize,
+		int32 count)
 	\brief Returns the next entries of the BDirectory object as a pointer
-		to dirent structures.
+	       to dirent structures.
 
 	Unlike GetNextEntry() and GetNextRef(), this method returns also
 	the entries "." and "..".
 
 	\note The iterator used by this method is the same one used by
-		GetNextEntry(), GetNextRef(), Rewind() and CountEntries().
+	      GetNextEntry(), GetNextRef(), Rewind() and CountEntries().
 
 	\param buf A pointer to a buffer filled with dirent structures containing
-		the found entries.
+	       the found entries.
 	\param bufSize The size of \a buf.
 	\param count The maximum number of entries to be returned.
 
 	\returns The number of dirent structures stored in the buffer, 0 when
-		there are no more entries to be returned or a status code on error.
+	         there are no more entries to be returned or a status code on
+	         error.
 	\retval B_BAD_VALUE \c NULL \a buf.
 	\retval B_PERMISSION_DENIED Directory permissions didn't allow operation.
 	\retval B_NO_MEMORY Insufficient memory for operation.
@@ -422,6 +470,8 @@
 	\retval B_BUSY A node was busy.
 	\retval B_FILE_ERROR A general file error.
 	\retval B_NO_MORE_FDS The application has run out of file descriptors.
+
+	\since BeOS R3
 */
 
 
@@ -442,6 +492,8 @@
 	\sa BDirectory::GetNextRef()
 	\sa BDirectory::GetNextDirents()
 	\sa BDirectory::CountEntries()
+
+	\since BeOS R3
 */
 
 
@@ -454,7 +506,7 @@
 	the entries and Rewind()s again. The entries "." and ".." are not counted.
 
 	\returns The number of entries in the directory (not counting "." and
-		"..") or a status code on error.
+	         "..") or a status code on error.
 	\retval B_PERMISSION_DENIED Directory permissions didn't allow operation.
 	\retval B_NO_MEMORY Insufficient memory for operation.
 	\retval B_LINK_LIMIT Indicates a cyclic loop within the file system.
@@ -466,6 +518,8 @@
 	\sa BDirectory::GetNextRef()
 	\sa BDirectory::GetNextDirents()
 	\sa BDirectory::Rewind()
+
+	\since BeOS R3
 */
 
 
@@ -477,9 +531,9 @@
 	an error status code.
 
 	\param path The new path name of the directory. May be a relative
-		path to this directory or an absolute path.
+	       path to this directory or an absolute path.
 	\param dir A pointer to a BDirectory to be initialized to the newly
-		created directory. May be \c NULL.
+	       created directory. May be \c NULL.
 
 	\returns A status code.
 	\retval B_OK Everything went fine.
@@ -492,6 +546,8 @@
 	\retval B_FILE_ERROR A general file error.
 	\retval B_FILE_EXISTS An entry with that name does already exist.
 	\retval B_NO_MORE_FDS The application has run out of file descriptors.
+
+	\since BeOS R3
 */
 
 
@@ -506,9 +562,9 @@
 	mode.
 
 	\param path The new file's path name. May be relative to this
-		directory or an absolute path.
+	       directory or an absolute path.
 	\param file A pointer to a BFile to be initialized to the newly
-		created file. May be \c NULL.
+	       created file. May be \c NULL.
 	\param failIfExists Whether or not to fail if the file already exists.
 
 	\returns A status code.
@@ -521,10 +577,12 @@
 	\retval B_BUSY A node was busy.
 	\retval B_FILE_ERROR A general file error.
 	\retval B_FILE_EXISTS A file with that name does already exist and
-		\c true has been passed for \a failIfExists.
+	        \c true has been passed for \a failIfExists.
 	\retval B_IS_A_DIRECTORY A directory with the supplied name already
-		exists.
+	        exists.
 	\retval B_NO_MORE_FDS The application has run out of file descriptors.
+
+	\since BeOS R3
 */
 
 
@@ -536,10 +594,10 @@
 	This method fails if an entry with the supplied name already exists.
 
 	\param path the new symbolic link's path name. May be relative to this
-		   directory or absolute.
+	       directory or absolute.
 	\param linkToPath the path the symbolic link shall point to.
 	\param link a pointer to a BSymLink to be initialized to the newly
-		   created symbolic link. May be \c NULL.
+	       created symbolic link. May be \c NULL.
 
 	\returns A status code.
 	\retval B_OK Everything went fine.
@@ -552,6 +610,8 @@
 	\retval B_FILE_ERROR A general file error.
 	\retval B_FILE_EXISTS An entry with that name does already exist.
 	\retval B_NO_MORE_FDS The application has run out of file descriptors.
+
+	\since BeOS R3
 */
 
 
@@ -566,6 +626,8 @@
 	\param dir The original BDirectory object.
 
 	\returns A reference to this BDirectory object.
+
+	\since BeOS R3
 */
 
 
@@ -577,6 +639,8 @@
 	member directly.
 
 	\returns the file descriptor, or -1 if not properly initialized.
+
+	\since Haiku R1
 */
 
 
@@ -586,7 +650,7 @@
 
 	\param path The directory path name.
 	\param mode A permission specification, which shall be used for the
-		   newly created directories.
+	       newly created directories.
 
 	\returns A status code.
 	\retval B_OK Everything went fine.
@@ -598,6 +662,8 @@
 	\retval B_BUSY A node was busy.
 	\retval B_FILE_ERROR A general file error.
 	\retval B_NOT_A_DIRECTORY An entry other than a directory with that name
-		already exists.
+	        already exists.
 	\retval B_NO_MORE_FDS The application has run out of file descriptors.
+
+	\since BeOS R3
 */

docs/user/storage/Entry.dox

@@ -1,5 +1,5 @@
 /*
- * Copyright 2011 Haiku, Inc. All rights reserved.
+ * Copyright 2011-2014 Haiku, Inc. All rights reserved.
  * Distributed under the terms of the MIT License.
  *
  * Authors:
@@ -8,8 +8,8 @@
  *		John Scipione, [email protected]
  *
  * Corresponds to:
- *		headers/os/storage/Entry.h  hrev43528
+ *		headers/os/storage/Entry.h	hrev47402
- *		src/kits/storage/Entry.cpp  hrev43528
+ *		src/kits/storage/Entry.cpp	hrev47402
  */
 
 
@@ -45,28 +45,34 @@
 	the old name (the upside in this case is that abstract entries may be
 	represented by entry_refs without preallocating an internal filesystem node
 	for them).
+
+	\since BeOS R3
 */
 
 
 /*!
 	\fn entry_ref::entry_ref()
 	\brief Creates an uninitialized entry_ref object.
+
+	\since BeOS R3
 */
 
 
 /*!
 	\fn entry_ref::entry_ref(dev_t dev, ino_t dir, const char* name)
 	\brief Creates an entry_ref object initialized to the given file name in
-		the given directory on the given device.
+	       the given directory on the given device.
 
 	\a name may refer to either a pre-existing file in the given directory, or
 	a non-existent file. No explicit checking is done to verify validity of the
 	given arguments, but later use of the entry_ref will fail if \p dev is not
 	a valid device or \a dir is a not a directory on \p dev.
 
-	\param dev the device on which the entry's parent directory resides
+	\param dev The \a device on which the entry's parent directory resides.
-	\param dir the directory in which the entry resides
+	\param dir The directory in which the entry resides.
-	\param name the leaf name of the entry, which is not required to exist
+	\param name The leaf name of the entry, which is not required to exist.
+
+	\since BeOS R3
 */
 
 
@@ -75,41 +81,51 @@
 	\brief Returns a copy of the passed in entry_ref object.
 
 	\param ref A reference to an entry_ref to copy.
+
+	\since BeOS R3
 */
 
 
 /*!
 	\fn entry_ref::~entry_ref()
 	\brief Destroys the object and frees the storage allocated for the leaf
-		name, if necessary.
+	       name, if necessary.
+
+	\since BeOS R3
 */
 
 
 /*!
 	\fn status_t entry_ref::set_name(const char* name)
 	\brief Set the entry_ref's leaf name, freeing the storage allocated for any
-		previous name and then making a copy of the new name.
+	       previous name and then making a copy of the new name.
 
 	\param name Pointer to a null-terminated string containing the new name for
-		the entry. May be \c NULL.
+	       the entry. May be \c NULL.
+
+	\since BeOS R3
 */
 
 
 /*!
 	\fn bool entry_ref::operator==(const entry_ref& ref) const
 	\brief Compares the entry_ref object with the passed in entry_ref,
-		returning \c true if they are equal.
+	       returning \c true if they are equal.
 
 	\returns \c true if he entry_refs are equal, \c false otherwise.
+
+	\since BeOS R3
 */
 
 
 /*!
 	\fn bool entry_ref::operator!=(const entry_ref& ref) const
 	\brief Compares the entry_ref object with the passed in entry_ref,
-		returning \c true if they are NOT equal.
+	       returning \c true if they are NOT equal.
 
 	\returns \c true if the entry_refs are NOT equal, \c false otherwise.
+
+	\since BeOS R3
 */
 
 
@@ -120,6 +136,8 @@
 	\param ref The entry_ref to copy.
 
 	\returns A pointer to the resulting entry_ref copy.
+
+	\since BeOS R5
 */
 
 
@@ -128,6 +146,7 @@
 
 	The device id of the storage device on which the entry resides.
 
+	\since BeOS R3
 */
 
 
@@ -135,6 +154,8 @@
 	\var ino_t entry_ref::directory
 
 	The inode number of the directory in which the entry resides.
+
+	\since BeOS R3
 */
 
 
@@ -142,6 +163,8 @@
 	\var char *entry_ref::name
 
 	The leaf name of the entry
+
+	\since BeOS R3
 */
 
 
@@ -170,10 +193,13 @@ BEntry entry("/boot/home/fido");
 
 	Should be followed by a call to one of the SetTo() methods, or an
 	assignment.
-	- SetTo(const BDirectory*, const char*, bool)
+
-	- SetTo(const entry_ref*, bool)
+	\sa SetTo(const BDirectory*, const char*, bool)
-	- SetTo(const char*, bool)
+	\sa SetTo(const entry_ref*, bool)
-	- operator=(const BEntry&)
+	\sa SetTo(const char*, bool)
+	\sa operator=(const BEntry&)
+
+	\since BeOS R3
 */
 
 
@@ -191,6 +217,8 @@ BEntry entry("/boot/home/fido");
 	\param traverse Whether or not to traverse symbolic links.
 
 	\see BEntry::SetTo(const BDirectory*, const char *, bool)
+
+	\since BeOS R3
 */
 
 
@@ -207,6 +235,8 @@ BEntry entry("/boot/home/fido");
 	\param traverse Whether or not symlinks are to be traversed.
 
 	\sa BEntry::SetTo(const entry_ref*, bool)
+
+	\since BeOS R3
 */
 
 
@@ -223,6 +253,8 @@ BEntry entry("/boot/home/fido");
 	\param traverse Whether or not symlinks are to be traversed.
 
 	\sa BEntry::SetTo(const char*, bool)
+
+	\since BeOS R3
 */
 
 
@@ -233,6 +265,8 @@ BEntry entry("/boot/home/fido");
 	\param entry the entry to be copied
 
 	\sa operator=(const BEntry&)
+
+	\since BeOS R3
 */
 
 
@@ -241,6 +275,8 @@ BEntry entry("/boot/home/fido");
 	\brief Frees all of the allocated resources of the BEntry.
 
 	\sa Unset()
+
+	\since BeOS R3
 */
 
 
@@ -251,7 +287,9 @@ BEntry entry("/boot/home/fido");
 	\returns A status code.
 	\retval B_OK Success
 	\retval B_NO_INIT The object has been Unset() or is uninitialized.
-*/
+
+	\since BeOS R3
+
 
 
 /*!
@@ -259,6 +297,8 @@ BEntry entry("/boot/home/fido");
 	\brief Returns whether or not the entry exists in the filesystem.
 
 	\returns \c true if the entry exists, \c false if not.
+
+	\since BeOS R3
 */
 
 
@@ -276,6 +316,8 @@ BEntry entry("/boot/home/fido");
 		information is copied.
 
 	\returns \c B_OK on success, or an error code on failure.
+
+	\since BeOS R3
 */
 
 
@@ -283,20 +325,22 @@ BEntry entry("/boot/home/fido");
 	\fn status_t BEntry::SetTo(const BDirectory* dir, const char* path,
 		bool traverse)
 	\brief Reinitializes the BEntry to the path or directory path combination,
-		resolving symlinks if traverse is \c true.
+	       resolving symlinks if traverse is \c true.
 
 	\param dir The base directory in which the \a path resides.
 	\param path Relative path based off of \a dir.
 	\param traverse Whether or not to traverse symbolic links.
 
 	\returns \c B_OK on success, or an error code on failure.
+
+	\since BeOS R3
 */
 
 
 /*!
 	\fn status_t BEntry::SetTo(const entry_ref* ref, bool traverse)
 	\brief Reinitializes the BEntry to the passed in entry_ref object
-		resolving symlinks if traverse is \c true.
+	       resolving symlinks if traverse is \c true.
 
 	\param ref The entry_ref referring to the given file.
 	\param traverse Whether or not symlinks are to be traversed.
@@ -304,13 +348,15 @@ BEntry entry("/boot/home/fido");
 	\returns \c B_OK on success, or an error code on failure.
 
 	\sa BEntry::BEntry(const entry_ref* ref, bool traverse)
+
+	\since BeOS R3
 */
 
 
 /*!
 	\fn status_t BEntry::SetTo(const char* path, bool traverse)
 	\brief Reinitializes the BEntry object to the path, resolving symlinks if
-		traverse is \c true.
+	       traverse is \c true.
 
 	\param path The path of the file.
 	\param traverse Whether or not symlinks are to be traversed.
@@ -318,12 +364,16 @@ BEntry entry("/boot/home/fido");
 	\returns \c B_OK on success, or an error code on failure.
 
 	\sa BEntry::BEntry(const char* path, bool traverse)
+
+	\since BeOS R3
 */
 
 
 /*!
 	void BEntry::Unset()
 	\brief Reinitializes the BEntry to an uninitialized BEntry object
+
+	\since BeOS R3
 */
 
 
@@ -335,6 +385,8 @@ BEntry entry("/boot/home/fido");
 		result is copied.
 
 	\returns \c B_OK on success, or an error code on failure.
+
+	\since BeOS R3
 */
 
 
@@ -346,6 +398,8 @@ BEntry entry("/boot/home/fido");
 		result is copied.
 
 	\returns \c B_OK on success, or an error code on failure.
+
+	\since BeOS R3
 */
 
 
@@ -382,12 +436,14 @@ if (err != B_ENTRY_NOT_FOUND)
 \endcode
 
 	\param entry A pointer to a pre-allocated BEntry object into which the
-		result is stored.
+	       result is stored.
 
 	\returns A status code.
 	\retval B_OK Success
 	\retval B_ENTRY_NOT_FOUND Attempted to get the parent of the root
-		directory.
+	        directory.
+
+	\since BeOS R3
 */
 
 
@@ -398,12 +454,14 @@ if (err != B_ENTRY_NOT_FOUND)
 	If the function fails, the argument is Unset().
 
 	\param dir A pointer to a pre-allocated BDirectory object into which the
-		result is copied.
+	       result is copied.
 
 	\returns A status code.
 	\retval B_OK Success
 	\retval B_ENTRY_NOT_FOUND Attempted to get the parent of the root
-		directory.
+	        directory.
+
+	\since BeOS R3
 */
 
 
@@ -415,32 +473,36 @@ if (err != B_ENTRY_NOT_FOUND)
 	entire string. A length of \c B_FILE_NAME_LENGTH is recommended.
 
 	\param buffer A pointer to a pre-allocated string into which the result
-		is copied.
+	       is copied.
 
 	\returns \c B_OK on success, or an error code on failure.
+
+	\since BeOS R3
 */
 
 
 /*!
 	\fn status_t BEntry::Rename(const char* path, bool clobber)
 	\brief Renames the BEntry to \a path replacing an existing entry
-		if \a clobber is \c true.
+	       if \a clobber is \c true.
 
 	\note The BEntry object must refer to an existing file, if it is abstract,
-		this method will fail.
+	      this method will fail.
 
 	\param path A pointer to a string containing the new name for the entry.
-		It may be an absolute or relative path. If it is a relative path the
+	       It may be an absolute or relative path. If it is a relative path
-		entry is renamed within its current directory.
+	       the entry is renamed within its current directory.
 	\param clobber If \c false and a file with the name given by \c path
-		already exists, the method will fail. If \c true and such a file
+	       already exists, the method will fail. If \c true and such a file
-		exists, it will be overwritten.
+	       exists, it will be overwritten.
 
 	\returns A status code.
 	\retval B_OK Success
 	\retval B_ENTRY_EXISTS The new location already exists and \c clobber
-		is \c false.
+	        is \c false.
 	\retval B_ENTRY_NOT_FOUND Attempted to rename an abstract entry.
+
+	\since BeOS R3
 */
 
 
@@ -454,19 +516,21 @@ if (err != B_ENTRY_NOT_FOUND)
 		this method will fail.
 
 	\param dir A pointer to a pre-allocated BDirectory into which the entry
-		should be moved.
+	       should be moved.
 	\param path (optional) new leaf name for the entry. May be a simple leaf
-		or a relative path; either way, \c path is reckoned off of \c dir. If
+	       or a relative path; either way, \c path is reckoned off of \c dir.
-		\c NULL, the entry retains its previous leaf name.
+	       If \c NULL, the entry retains its previous leaf name.
 	\param clobber If \c false and an entry already exists at the specified
-		destination, the method will fail. If \c true and such an entry exists,
+	       Spdestination, the method will fail. If \c true and such an entry
-		it will be overwritten.
+	       exists, it will be overwritten.
 
 	\returns A status code.
 	\retval B_OK Success
 	\retval B_ENTRY_EXISTS The new location already exists and \c clobber
-		is \c false.
+	        is \c false.
 	\retval B_ENTRY_NOT_FOUND Attempted to rename an abstract entry.
+
+	\since BeOS R3
 */
 
 
@@ -480,28 +544,36 @@ if (err != B_ENTRY_NOT_FOUND)
 	no longer refers to any actual data in the filesystem.
 
 	\returns \c B_OK on success, or an error code on failure.
+
+	\since BeOS R3
 */
 
 
 /*!
 	\fn bool BEntry::operator==(const BEntry& item) const
 	\brief Returns \c true if the BEntry and \a item refer to the same entry
-		or if they are both uninitialized.
+	       or if they are both uninitialized.
 
+	\returns Whether or not the items refer to the same entry.
 	\retval true Both BEntry objects refer to the same entry or they are
-		both uninitialized.
+	        both uninitialized.
 	\retval false The BEntry objects refer to different entries.
+
+	\since BeOS R3
 */
 
 
 /*!
 	\fn bool BEntry::operator!=(const BEntry& item) const
 	\brief Returns false if the BEntry and \c item refer to the same entry or
-		if they are both uninitialized.
+	       if they are both uninitialized.
 
+	\returns Whether or not the items do NOT refer to the same entry.
 	\retval true The BEntry objects refer to different entries.
 	\retval false Both BEntry objects refer to the same entry or they are
-		both uninitialized.
+	        both uninitialized.
+
+	\since BeOS R3
 */
 
 
@@ -510,91 +582,8 @@ if (err != B_ENTRY_NOT_FOUND)
 	\brief Reinitializes the BEntry to be a copy of \a item.
 
 	\returns A pointer to the copy.
-*/
 
-
+	\since BeOS R3
-/*!
-	\fn status_t BEntry::set_stat(struct stat& st, uint32 what)
-	\brief Updates the BEntry with the data from the stat structure according
-		to the \a what mask.
-
-	\param st The stat structure to set.
-	\param what A mask
-
-	\returns A status code.
-	\retval B_OK Everything went fine.
-	\retval B_FILE_ERROR There was an error writing to the BEntry object.
-*/
-
-
-/*!
-	\fn status_t BEntry::_SetTo(int dirFD, const char* path, bool traverse)
-	\brief Sets the entry to point to the entry specified by the path \a path
-	relative to the given directory.
-
-	If \a traverse is \c true and the given entry is a symbolic link, the
-	object is recursively set to point to the entry pointed to by the symlink.
-
-	If \a path is an absolute path, \a dirFD is ignored.
-
-	If \a dirFD is -1, \a path is considered relative to the current directory
-	(unless it is an absolute path).
-
-	The ownership of the file descriptor \a dirFD is transferred to the
-	method, regardless of whether it succeeds or fails. The caller must not
-	close the FD afterwards.
-
-	\param dirFD File descriptor of a directory relative to which path is to
-		be considered. May be -1 if the current directory shall be considered.
-	\param path Pointer to a path relative to the given directory.
-	\param traverse If \c true and the given entry is a symbolic link, the
-		object is recursively set to point to the entry linked to by the
-		symbolic link.
-
-	\returns \c B_OK on success, or an error code on failure.
-*/
-
-
-/*!
-	\fn status_t BEntry::_SetName(const char* name)
-	\brief Handles string allocation, deallocation, and copying for the
-		leaf name of the entry.
-
-	\param name The leaf \a name of the entry.
-
-	\returns A status code.
-	\retval B_OK Everything went fine.
-	\retval B_BAD_VALUE \a name is \c NULL.
-	\retval B_NO_MEMORY Ran out of memory trying to allocate \a name.
-*/
-
-
-/*!
-	\fn status_t BEntry::_Rename(BEntry& target, bool clobber)
-	\brief Renames the entry referred to by this object to the location
-		specified by \a target.
-
-	If an entry exists at the target location, the method fails, unless
-	\a clobber is \c true, in which case that entry is overwritten (doesn't
-	work for non-empty directories, though).
-
-	If the operation was successful, this entry is made a clone of the
-	supplied one and the supplied one is uninitialized.
-
-	\param target The entry specifying the target location.
-	\param clobber If \c true, the an entry existing at the target location
-		   will be overwritten.
-
-	\return \c B_OK, if everything went fine, another error code otherwise.
-*/
-
-
-/*!
-	\fn void BEntry::_Dump(const char* name)
-	\brief Debugging function, dumps the given entry to stdout.
-
-	\param name A pointer to a string to be printed along with the dump for
-		identification purposes.
 */
 
 
@@ -610,6 +599,8 @@ if (err != B_ENTRY_NOT_FOUND)
 	\retval B_BAD_VALUE \c NULL \a path or \a ref.
 	\retval B_ENTRY_NOT_FOUND A (non-leaf) path component does not exist.
 	\retval B_NO_MEMORY Insufficient memory for successful completion.
+
+	\since BeOS R4
 */
 
 
@@ -622,4 +613,6 @@ if (err != B_ENTRY_NOT_FOUND)
 
 	\retval true a < b
 	\retval false a >= b
+
+	\since Haiku R1
 */

docs/user/storage/EntryList.dox

@@ -1,5 +1,5 @@
 /*
- * Copyright 2011 Haiku, Inc. All rights reserved.
+ * Copyright 2011-2014 Haiku, Inc. All rights reserved.
  * Distributed under the terms of the MIT License.
  *
  * Authors:
@@ -7,8 +7,8 @@
  *		John Scipione, [email protected]
  * 
  * Corresponds to:
- *		headers/os/storage/EntryList.h	 rev 42794
+ *		headers/os/storage/EntryList.h	 hrev47402
- *		src/kits/storage/EntryList.cpp	 rev 42794
+ *		src/kits/storage/EntryList.cpp	 hrev47402
  */
 
 
@@ -28,6 +28,8 @@
 
 	Defines a general interface for iterating through a list of entries
 	i.e. files in a folder.
+
+	\since BeOS R3
 */
 
 
@@ -36,6 +38,8 @@
 	\brief Creates a BEntryList object.
 
 	Does nothing at this time.
+
+	\since Haiku R1
 */
 
 
@@ -44,6 +48,8 @@
 	\brief Frees all resources associated with the BEntryList object.
 
 	Does nothing at this time.
+
+	\since Haiku R1
 */
 
 
@@ -56,15 +62,17 @@
 
 	\param entry a pointer to a BEntry to be initialized with the found entry.
 	\param traverse specifies whether to follow it, if the found entry
-		   is a symbolic link.
+	       is a symbolic link.
 
 	\note The iterator used by this method is the same one used by
-		  GetNextRef(), GetNextDirents(), Rewind() and CountEntries().
+	      GetNextRef(), GetNextDirents(), Rewind() and CountEntries().
 
 	\retval B_OK if successful
 	\retval B_ENTRY_NOT_FOUND when at the end of the list
 	\retval B_ERROR or another error code (depending on the implementation
-		of the derived class).
+	        of the derived class).
+
+	\since BeOS R3
 */
 
 
@@ -75,21 +83,23 @@
 	Places an entry_ref to the next entry in the list into \a ref.
 
 	\param ref a pointer to an entry_ref to be filled in with the data of the
-		   found entry.
+	       found entry.
 
 	\note The iterator used by this method is the same one used by
-		  GetNextEntry(), GetNextDirents(), Rewind() and CountEntries().
+	      GetNextEntry(), GetNextDirents(), Rewind() and CountEntries().
 
 	\retval B_OK if successful
 	\retval B_ENTRY_NOT_FOUND when at the end of the list
 	\retval B_ERROR or another error code (depending on the implementation
-		of the derived class).
+	        of the derived class).
+
+	\since BeOS R3
 */
 
 
 /*!
 	\fn int32 BEntryList::GetNextDirents(struct dirent *buf, size_t length,
-										 int32 count)
+		int32 count)
 	\brief Returns the BEntryList's next entries as dirent structures.
 
 	Reads a number of entries into the array of dirent structures pointed
@@ -98,18 +108,20 @@
 	\a buf with given length \a length (in bytes), whichever is smallest.
 
 	\param buf A pointer to a buffer to be filled with dirent structures of
-		the found entries.
+	       the found entries.
 	\param length The length of the \a buf array.
 	\param count the maximum number of entries to be read.
 
 	\note The iterator used by this method is the same one used by
-		  GetNextEntry(), GetNextRef(), Rewind() and CountEntries().
+	      GetNextEntry(), GetNextRef(), Rewind() and CountEntries().
 
 	\returns
-		- The number of dirent structures stored in the buffer or 0 when
+	- The number of dirent structures stored in the buffer or 0 when
-			there are no more entries to be read.
+		there are no more entries to be read.
-		- an error code (depending on the implementation of the derived class)
+	- an error code (depending on the implementation of the derived class)
-			if an error occurred.
+		if an error occurred.
+
+	\since BeOS R3
 */
 
 
@@ -119,7 +131,9 @@
 
 	\retval B_OK if successful
 	\retval B_ERROR or another error code (depending on the implementation
-		of the derived class).
+	        of the derived class).
+
+	\since BeOS R3
 */
 
 
@@ -130,5 +144,7 @@
 	\retval B_OK if successful
 	\retval B_ENTRY_NOT_FOUND when at the end of the list
 	\retval B_ERROR or another error code (depending on the implementation
-		of the derived class).
+	        of the derived class).
-*/
+
+	\since BeOS R3
+*/

docs/user/storage/File.dox

@@ -1,5 +1,5 @@
 /*
- * Copyright 2009-2012 Haiku, Inc. All rights reserved.
+ * Copyright 2009-2014 Haiku, Inc. All rights reserved.
  * Distributed under the terms of the MIT License.
  *
  * Authors:
@@ -8,8 +8,8 @@
  *		Ingo Weinhold, [email protected]
  *
  * Corresponds to:
- *		headers/os/storage/File.h  hrev45060
+ *		headers/os/storage/File.h	hrev47402
- *		src/kits/storage/File.cpp  hrev45060
+ *		src/kits/storage/File.cpp	hrev47402
  */
 
 
@@ -33,6 +33,8 @@
 	Symbolic links are automatically transversed by opening a BFile.
 	The node that the BFile ends up opening will be the file or directory
 	that the link points to, not the symbolic link file itself.
+
+	\since BeOS R3
 */
 
 
@@ -47,6 +49,8 @@
 	- SetTo(const char* path, uint32 openMode)
 	- SetTo(const BDirectory* dir, const char* path, uint32 openMode)
 	- operator=(const BFile &file)
+
+	\since BeOS R3
 */
 
 
@@ -57,57 +61,67 @@
 	If \a file is uninitialized, the newly constructed BFile will be too.
 
 	\param file The BFile object to be copied.
+
+	\since BeOS R3
 */
 
 
 /*!
 	\fn BFile::BFile(const entry_ref* ref, uint32 openMode)
 	\brief Creates a BFile and initializes it to the file referred to by
-		   the supplied entry_ref and according to the specified open mode.
+	       the supplied entry_ref and according to the specified open mode.
 
 	\param ref The entry_ref referring to the file.
 	\param openMode The mode in which the file should be opened.
 
 	\see SetTo(const entry_ref* ref, uint32 openMode)
+
+	\since BeOS R3
 */
 
 
 /*!
 	\fn BFile::BFile(const BEntry* entry, uint32 openMode)
 	\brief Creates a BFile and initializes it to the file referred to by
-		   the supplied BEntry and according to the specified open mode.
+	       the supplied BEntry and according to the specified open mode.
 
 	\param entry The BEntry referring to the file.
 	\param openMode The mode in which the file should be opened.
 
 	\see SetTo(const BEntry* entry, uint32 openMode)
+
+	\since BeOS R3
 */
 
 
 /*!
 	\fn BFile::BFile(const char* path, uint32 openMode)
 	\brief Creates a BFile and initializes it to the file referred to by
-		   the supplied path name and according to the specified open mode.
+	       the supplied path name and according to the specified open mode.
 
 	\param path The file's path name.
 	\param openMode The mode in which the file should be opened.
 
 	\see SetTo(const char* path, uint32 openMode)
+
+	\since BeOS R3
 */
 
 
 /*!
 	\fn BFile::BFile(const BDirectory *dir, const char* path, uint32 openMode)
 	\brief Creates a BFile and initializes it to the file referred to by
-		   the supplied path name relative to the specified BDirectory and
+	       the supplied path name relative to the specified BDirectory and
-		   according to the specified open mode.
+	       according to the specified open mode.
 
 	\param dir The BDirectory, relative to which the file's path name is
-		   given.
+	       given.
 	\param path The file's path name relative to \a dir.
 	\param openMode The mode in which the file should be opened.
 
 	\see SetTo(const BDirectory* dir, const char* path, uint32 openMode)
+
+	\since BeOS R3
 */
 
 
@@ -116,27 +130,30 @@
 	\brief Destroys the BFile object and frees all allocated resources.
 
 	If the file is properly initialized, the file descriptor is closed.
+
+	\since BeOS R3
 */
 
 
 /*!
 	\fn status_t BFile::SetTo(const entry_ref* ref, uint32 openMode)
 	\brief Re-initializes the BFile to the file referred to by the
-		   supplied entry_ref and according to the specified open mode.
+	       supplied entry_ref and according to the specified open mode.
 
 	\param ref The entry_ref referring to the file.
 	\param openMode The mode in which the file should be opened
-		\a openMode must be a bitwise or of exactly one of the flags.
+	       \a openMode must be a bitwise or of exactly one of the flags.
-		- \c B_READ_ONLY: The file is opened read only.
+	       - \c B_READ_ONLY: The file is opened read only.
-		- \c B_WRITE_ONLY: The file is opened write only.
+	       - \c B_WRITE_ONLY: The file is opened write only.
-		- \c B_READ_WRITE: The file is opened for random read/write access.
+	       - \c B_READ_WRITE: The file is opened for random read/write access.
-		and any number of the flags
+	         and any number of the flags
-		- \c B_CREATE_FILE: A new file will be created, if it does not already
+	       - \c B_CREATE_FILE: A new file will be created, if it does not
-			exist.
+	         already exist.
-		- \c B_FAIL_IF_EXISTS: If the file does already exist and
+	       - \c B_FAIL_IF_EXISTS: If the file does already exist and
-			\c B_CREATE_FILE is set, SetTo() fails.
+	         \c B_CREATE_FILE is set, SetTo() fails.
-		- \c B_ERASE_FILE: An already existing file is truncated to zero size.
+	       - \c B_ERASE_FILE: An already existing file is truncated to zero
-		- \c B_OPEN_AT_END: Seek() to the end of the file after opening.
+	         size.
+	       - \c B_OPEN_AT_END: Seek() to the end of the file after opening.
 
 	\returns A status code.
 	\retval B_OK Everything went fine.
@@ -149,13 +166,15 @@
 	\retval B_BUSY A node was busy.
 	\retval B_FILE_ERROR A general file error.
 	\retval B_NO_MORE_FDS The application has run out of file descriptors.
+
+	\since BeOS R3
 */
 
 
 /*!
 	\fn status_t BFile::SetTo(const BEntry* entry, uint32 openMode)
 	\brief Re-initializes the BFile to the file referred to by the
-		   supplied BEntry and according to the specified open mode.
+	       supplied BEntry and according to the specified open mode.
 
 	\param entry the BEntry referring to the file
 	\param openMode the mode in which the file should be opened
@@ -173,14 +192,16 @@
 	\retval B_NO_MORE_FDS The application has run out of file descriptors.
 
 	\todo Implemented using SetTo(entry_ref*, uint32). Check, if necessary
-		  to re-implement!
+	      to re-implement!
+
+	\since BeOS R3
 */
 
 
 /*!
 	\fn status_t BFile::SetTo(const char* path, uint32 openMode)
 	\brief Re-initializes the BFile to the file referred to by the
-		   supplied path name and according to the specified open mode.
+	       supplied path name and according to the specified open mode.
 
 	\param path The file's path name.
 	\param openMode The mode in which the file should be opened.
@@ -196,19 +217,20 @@
 	\retval B_BUSY A node was busy.
 	\retval B_FILE_ERROR A general file error.
 	\retval B_NO_MORE_FDS The application has run out of file descriptors.
-*/
+
+	\since BeOS R3
 */
 
 
 /*!
 	\fn status_t BFile::SetTo(const BDirectory* dir, const char* path,
-		uint32 openMode)
+	    uint32 openMode)
 	\brief Re-initializes the BFile to the file referred to by the
-		   supplied path name relative to the specified BDirectory and
+	       supplied path name relative to the specified BDirectory and
-		   according to the specified open mode.
+	       according to the specified open mode.
 
 	\param dir The BDirectory, relative to which the file's path name is
-		   given.
+	       given.
 	\param path The file's path name relative to \a dir.
 	\param openMode The mode in which the file should be opened.
 
@@ -225,7 +247,9 @@
 	\retval B_NO_MORE_FDS The application has run out of file descriptors.
 
 	\todo Implemented using SetTo(BEntry*, uint32). Check, if necessary
-		  to re-implement!
+	      to re-implement!
+
+	\since BeOS R3
 */
 
 
@@ -237,6 +261,8 @@
 	- \c true, if the BFile has been initialized properly and the file has
 	  been been opened for reading,
 	- \c false, otherwise.
+
+	\since BeOS R3
 */
 
 
@@ -248,6 +274,8 @@
 	- \c true, if the BFile has been initialized properly and the file has
 	  been opened for writing,
 	- \c false, otherwise.
+
+	\since BeOS R3
 */
 
 
@@ -259,20 +287,24 @@
 	\param size The number of bytes that shall be read.
 
 	\returns The number of bytes read or an error code.
+
+	\since BeOS R3
 */
 
 
 /*!
 	\fn ssize_t BFile::ReadAt(off_t location, void* buffer, size_t size)
 	\brief Reads a number of bytes from a certain position within the file
-		   into a buffer.
+	       into a buffer.
 
 	\param location The position (in bytes) within the file from which the
-		   data shall be read.
+	       data shall be read.
 	\param buffer The buffer the data from the file shall be written to.
 	\param size The number of bytes that shall be read.
 
 	\returns The number of bytes read or an error code.
+
+	\since BeOS R3
 */
 
 
@@ -284,20 +316,24 @@
 	\param size The number of bytes that shall be written.
 
 	\returns The number of bytes actually written or an error code.
+
+	\since BeOS R3
 */
 
 
 /*!
 	\fn ssize_t BFile::WriteAt(off_t location, const void* buffer, size_t size)
-	\brief \brief Writes a number of bytes from a buffer at a certain position
+	\brief Writes a number of bytes from a buffer at a certain position
-		   into the file.
+	       into the file.
 
 	\param location The position (in bytes) within the file at which the data
-		   shall be written.
+	       shall be written.
 	\param buffer The buffer containing the data to be written to the file.
 	\param size The number of bytes that shall be written.
 
 	\returns The number of bytes actually written or an error code.
+
+	\since BeOS R3
 */
 
 
@@ -311,16 +347,18 @@
 	or Write() invocations will be undefined.
 
 	\param offset New read/write position, depending on \a seekMode relative
-		   to the beginning or the end of the file or the current position.
+	       to the beginning or the end of the file or the current position.
 	\param seekMode
-		- \c SEEK_SET: move relative to the beginning of the file
+	       - \c SEEK_SET: move relative to the beginning of the file.
-		- \c SEEK_CUR: move relative to the current position
+	       - \c SEEK_CUR: move relative to the current position.
-		- \c SEEK_END: move relative to the end of the file
+	       - \c SEEK_END: move relative to the end of the file.
 
 	\returns The new read/write position relative to the beginning of the
-		file or an error code.
+	         file or an error code.
 	\retval B_ERROR Trying to seek before the beginning of the file.
 	\retval B_FILE_ERROR The file is not properly initialized.
+
+	\since BeOS R3
 */
 
 
@@ -329,9 +367,11 @@
 	\brief Gets the current read/write position within the file.
 
 	\returns The current read/write position relative to the beginning of the
-		file or an error code.
+	         file or an error code.
 	\retval B_ERROR After a Seek() before the beginning of the file.
 	\retval B_FILE_ERROR The file has not been initialized.
+
+	\since BeOS R3
 */
 
 
@@ -344,15 +384,17 @@
 	truncated.
 
 	\note There's no problem with setting the size of a BFile opened in
-		  \c B_READ_ONLY mode, unless the file resides on a read only volume.
+	      \c B_READ_ONLY mode, unless the file resides on a read only volume.
 
 	\param size The new file size.
 
 	\returns A status code.
 	\retval B_OK Everything went fine.
 	\retval B_NOT_ALLOWED Trying to set the size of a file on a read only
-			volume.
+	        volume.
 	\retval B_DEVICE_FULL There's not enough space left on the volume.
+
+	\since BeOS R3
 */
 
 
@@ -365,6 +407,8 @@
 	\returns A status code.
 
 	\see BStatable::GetSize()
+
+	\since BeOS R3
 */
 
 
@@ -378,20 +422,6 @@
 	\param file The original BFile to assign from.
 
 	\returns A reference to the assigned BFile.
-*/
+
-
+	\since BeOS R3
-
-/*!
-	\fn int BFile::get_fd() const
-	\brief Gets the file descriptor of the BFile.
-
-	To be used instead of accessing the BNode's private \c fFd member directly.
-
-	\returns The file descriptor, or -1 if not properly initialized.
-*/
-
-
-/*!
-	\fn void BFile::close_fd()
-	\brief Overrides BNode::close_fd() for binary compatibility with BeOS R5.
 */

docs/user/storage/FilePanel.dox

@@ -1,13 +1,13 @@
 /*
- * Copyright 2009-2012 Haiku, Inc. All rights reserved.
+ * Copyright 2009-2014 Haiku, Inc. All rights reserved.
  * Distributed under the terms of the MIT License.
  *
  * Authors:
  *		John Scipione, [email protected]
  *
  * Corresponds to:
- *		headers/os/storage/FilePanel.h  hrev45162
+ *		headers/os/storage/FilePanel.h	hrev47402
- *		src/kits/tracker/FilePanel.cpp  hrev45162
+ *		src/kits/tracker/FilePanel.cpp	hrev47402
  */
 
 
@@ -23,6 +23,8 @@
 	\enum file_panel_mode
 	\ingroup storage
 	\brief Whether the file panel is a save or open panel.
+
+	\since BeOS R3
 */
 
 
@@ -30,12 +32,16 @@
 	\var file_panel_mode B_OPEN_PANEL
 
 	Open panel
+
+	\since BeOS R3
 */
 
 
 /*!
 	\var file_panel_mode B_SAVE_PANEL
 
+
+	\since BeOS R3
 	Save panel
 */
 
@@ -43,7 +49,9 @@
 /*!
 	\enum file_panel_button
 	\ingroup storage
-	\brief List of buttons used by the file panel
+	\brief List of buttons used by the file panel.
+
+	\since BeOS R3
 */
 
 
@@ -51,6 +59,8 @@
 	\var file_panel_button B_CANCEL_BUTTON
 
 	Cancel button
+
+	\since BeOS R3
 */
 
 
@@ -58,6 +68,8 @@
 	\var file_panel_button B_DEFAULT_BUTTON
 
 	Default button
+
+	\since BeOS R3
 */
 
 
@@ -66,6 +78,8 @@
 	\ingroup storage
 	\ingroup libbe
 	\brief Allows you to filter the items displayed in a file panel.
+
+	\since BeOS R3
 */
 
 
@@ -73,7 +87,7 @@
 	\fn virtual bool BRefFilter::Filter(const entry_ref* ref, BNode* node,
 		struct stat_beos* stat, const char* mimeType)
 	\brief Hook method that's called on each file in the target directory
-		displayed by a file panel.
+	       displayed by a file panel.
 
 	\param ref The file currently under consideration.
 	\param node The node currently under consideration.
@@ -81,9 +95,11 @@
 	\param mimeType The MIME type of the file.
 
 	\returns Whether or not the entry is a valid candidate for an open/save
-		dialog.
+	         dialog.
 
 	\see BFilePanel::SetRefFilter()
+
+	\since BeOS R3
 */
 
 
@@ -172,6 +188,8 @@
 	destroyed, it is hidden instead. You can then delete the BFilePanel
 	object or leave it be and simply call Show() to use the panel next time
 	you need it.
+
+	\since BeOS R3
 */
 
 
@@ -189,22 +207,28 @@
 	SetRefFilter(), and SetHideWhenDone() methods.
 
 	\param mode Set to \c B_OPEN_PANEL for an open panal or \c B_SAVE_PANEL
-		for a save panel. Default is \c B_OPEN_PANEL.
+	       for a save panel. Default is \c B_OPEN_PANEL.
 	\param target The BMessenger object that sends messages to the BLooper
-		or BHandler controlled by the file panel.
+	       or BHandler controlled by the file panel.
 	\param ref The directory to display, by default the current working
-		directory.
+	       directory.
-	\param nodeFlavors One or more option flags, this applies to open panels only.
+	\param nodeFlavors One or more option flags, this applies to open panels
-		- \c B_FILE_NODE Can select files and symlinks to files.
+	       only.
-		- \c B_DIRECTORY_NODE Can select directories and symlinks to directories.
+	       - \c B_FILE_NODE Can select files and symlinks to files.
-		- \c B_SYMLINK_NODE Can select symlinks only.
+	       - \c B_DIRECTORY_NODE Can select directories and symlinks to
+	         directories.
+	       - \c B_SYMLINK_NODE Can select symlinks only.
 	\param multipleSelection Whether or not the user is allowed to select more
-		than one item to open. Save panels should always set this to \c false.
+	       than one item to open. Save panels should always set this to
+	       \c false.
 	\param message Message sent by the file panel on confirms or cancels.
 	\param filter Hook method to call.
 	\param modal Whether or not the panel is modal, defaults to \c false.
 	\param hideWhenDone Set to \c false to keep the panel even after the user
-		confirms or cancels. The close button will hide the panel regardless.
+	       confirms or cancels. The close button will hide the panel
+	       regardless.
+
+	\since BeOS R3
 */
 
 
@@ -214,18 +238,24 @@
 
 	If file panel is currently being displayed it is closed. The BRefFilter
 	object references by this panel is not destroyed by this method.
+
+	\since BeOS R3
 */
 
 
 /*!
 	\fn void BFilePanel::Show()
 	\brief Displays the file panel on screen.
+
+	\since BeOS R3
 */
 
 
 /*!
 	\fn void BFilePanel::Hide()
 	\brief Hides the file panel.
+
+	\since BeOS R3
 */
 
 
@@ -234,6 +264,10 @@
 	\brief Determines whether or not the file panel is shown.
 
 	\returns \c true if visible, \c false if hidden.
+
+	\see Show()
+
+	\since BeOS R3
 */
 
 
@@ -246,6 +280,8 @@
 	\param message The message to send.
 
 	\see BMessenger::SendMessage()
+
+	\since BeOS R3
 */
 
 
@@ -253,8 +289,10 @@
 	\fn file_panel_mode BFilePanel::PanelMode() const
 	\brief Gets the panel mode, either \c B_OPEN_PANEL or \c B_SAVE_PANEL.
 
-	\returns \c B_OPEN_PANEL if the panel is an open panel or \c B_SAVE_PANEL
+	\returns \c B_OPEN_PANEL if the panel is an open panel, or \c B_SAVE_PANEL
-		if the panel is a save panel.
+	         if the panel is a save panel.
+
+	\since BeOS R3
 */
 
 
@@ -263,6 +301,8 @@
 	\brief Gets the panel's target messenger object.
 
 	\returns The BMessenger object that sends messages for this panel.
+
+	\since BeOS R3
 */
 
 
@@ -271,6 +311,8 @@
 	\brief Sets the target messenger.
 
 	\param target the target BMessenger object to set.
+
+	\since BeOS R3
 */
 
 
@@ -279,13 +321,17 @@
 	\brief Sets the target messenge.
 
 	\param message The BMessage object to send on confirm.
+
+	\since BeOS R3
 */
 
 
 /*!
 	\fn void BFilePanel::Refresh()
 	\brief Refresh the directory or the panel causing the entries to be re-run
-		through the BRefFilter::Filter() method.
+	       through the BRefFilter::Filter() method.
+
+	\since BeOS R3
 */
 
 
@@ -296,6 +342,8 @@
 	\returns The BRefFilter set to the panel.
 
 	\see BRefFilter::Filter()
+
+	\since BeOS R3
 */
 
 
@@ -306,6 +354,8 @@
 	\param filter The BRefFilter object to set.
 
 	\see BRefFilter::Filter()
+
+	\since BeOS R3
 */
 
 
@@ -316,6 +366,8 @@
 
 	\param button The button to set the label of.
 	\param text The text to set the button label to.
+
+	\since BeOS R3
 */
 
 
@@ -324,6 +376,8 @@
 	\brief Gets the entry ref of the panel and sets \a ref to point to it.
 
 	\param ref The \c entry_ref pointer you want set.
+
+	\since BeOS R3
 */
 
 
@@ -332,42 +386,52 @@
 	\brief Set some save text to display in the save dialog.
 
 	\param text The text to display.
+
+	\since BeOS R3
 */
 
 
 /*!
 	\fn void BFilePanel::SetPanelDirectory(const entry_ref* ref)
 	\brief Sets the entry ref of the panel to the directory contained
-		by \a ref.
+	       by \a ref.
 
 	\param ref The entry contained by the desired panel directory.
+
+	\since BeOS R3
 */
 
 
 /*!
 	\fn void BFilePanel::SetPanelDirectory(const char* path)
 	\brief Sets the entry ref of the panel to the directory referenced
-		by \a path.
+	       by \a path.
 
 	\param path The path of the desired directory.
+
+	\since BeOS R3
 */
 
 
 /*!
 	\fn void BFilePanel::SetPanelDirectory(const BEntry* entry)
 	\brief Sets the entry ref of the panel to the directory referenced
-		by \a entry.
+	       by \a entry.
 
 	\param entry The BEntry object pointing to the desired directory.
+
+	\since BeOS R3
 */
 
 
 /*!
 	\fn void BFilePanel::SetPanelDirectory(const BDirectory* dir)
 	\brief Sets the entry ref of the panel to the directory referenced
-		by \a dir.
+	       by \a dir.
 
 	\param dir The BDirectory object pointing to the desired directory.
+
+	\since BeOS R3
 */
 
 
@@ -376,6 +440,8 @@
 	\brief Gets a pointer to the BWindow object used by the file panel.
 
 	\returns A pointer to the BWindow object used by the file panel.
+
+	\since BeOS R3
 */
 
 
@@ -384,6 +450,8 @@
 	\brief Sets the entry ref back to the top of the list.
 
 	\see SelectionChanged()
+
+	\since BeOS R3
 */
 
 
@@ -396,7 +464,10 @@
 	\retval B_ERROR Couldn't attain a lock on the window.
 	\retval B_ENTRY_NOT_FOUND End of the entry list.
 
+	\see Rewind()
 	\see SelectionChanged()
+
+	\since BeOS R3
 */
 
 
@@ -405,6 +476,8 @@
 	\brief Sets whether or not the panel should hide on confirm or cancel.
 
 	\param on \c true to hide, \c false to not hide when done.
+
+	\since BeOS R3
 */
 
 
@@ -415,23 +488,42 @@
 	Panel always hides if the user clicks the window's close button.
 
 	\returns \c true if panel will hide, \c false if panel will not hide.
+
+	\see SetHideWhenDone()
+
+	\since BeOS R3
 */
 
 
+/*!
+	\name Hook Methods
+*/
+
+
+//! @{
+
+
 /*!
 	\fn void BFilePanel::WasHidden()
 	\brief Hook method that gets called when the file panel is hidden due to
-		a user action.
+	       a user action.
 
 	WasHidden() is not called if you call Hide() manually.
+
+	\since BeOS R3
 */
 
 
 /*!
 	\fn void BFilePanel::SelectionChanged()
 	\brief Hook method that gets called when the entry ref references by the
-		file panel changes.
+	       file panel changes.
 
 	\see GetNextSelectedRef()
 	\see Rewind()
+
+	\since BeOS R3
 */
+
+
+//! @}

docs/user/storage/Mime.dox

@@ -1,5 +1,5 @@
 /*
- * Copyright 2013 Haiku Inc. All rights reserved.
+ * Copyright 2013-2014 Haiku, Inc. All rights reserved.
  * Distributed under the terms of the MIT License.
  *
  * Authors:
@@ -7,8 +7,8 @@
  *		John Scipione, [email protected]
  *
  * Corresponds to:
- *		headers/os/storage/Mime.h	 hrev45224
+ *		headers/os/storage/Mime.h	 hrev47402
- *		src/kits/storage/Mime.cpp	 hrev45224
+ *		src/kits/storage/Mime.cpp	 hrev47402
  */
 
 
@@ -24,6 +24,8 @@
 	\enum icon_size
 	\ingroup storage
 	\brief Legacy BeOS icon size constants.
+
+	\since BeOS R3
 */
 
 
@@ -31,6 +33,8 @@
 	\var icon_size B_LARGE_ICON
 
 	32x32 "Large" icon.
+
+	\since BeOS R3
 */
 
 
@@ -38,34 +42,39 @@
 	\var icon_size B_MINI_ICON
 
 	16x16 "Mini" icon.
+
+	\since BeOS R3
 */
 
 
 /*!
 	\var B_UPDATE_MIME_INFO_NO_FORCE
+	\brief Files that already have a \c BEOS:TYPE attribute won't be updated.
 
-	Files that already have a \c BEOS:TYPE attribute won't be updated.
+	\since Haiku R1
 */
 
 
 /*!
 	\var B_UPDATE_MIME_INFO_FORCE_KEEP_TYPE
+	\brief Files that already have a \c BEOS:TYPE attribute will be updated
+	       too, but \c BEOS:TYPE itself will remain untouched.
 
-	Files that already have a \c BEOS:TYPE attribute will be updated too, but
+	\since Haiku R1
-	\c BEOS:TYPE itself will remain untouched.
 */
 
 
 /*!
 	\var B_UPDATE_MIME_INFO_FORCE_UPDATE_ALL
+	\brief Similar to \c B_UPDATE_MIME_INFO_FORCE_KEEP_TYPE, but the
+	       \c BEOS:TYPE attribute will be updated too.
 
-	Similar to \c B_UPDATE_MIME_INFO_FORCE_KEEP_TYPE, but the \c BEOS:TYPE
+	\since Haiku R1
-	attribute will be updated too.
 */
 
 
 /*!
-	\fn int update_mime_info(const char *path, int recursive, int synchronous,
+	\fn int update_mime_info(const char* path, int recursive, int synchronous,
 		int force)
 	\brief Updates the MIME information (i.e MIME type) for one or more files.
 
@@ -78,21 +87,23 @@
 	\param path The path to a file or directory, or \c NULL.
 	\param recursive Triggers recursive behavior if not \c NULL.
 	\param synchronous If not \c NULL update_mime_info() waits until the
-		operation is finished, otherwise it returns immediately and the
+	       operation is finished, otherwise it returns immediately and the
-		update is done asynchronously.
+	       update is done asynchronously.
 	\param force Specifies how to handle files that already have MIME
-		   information. See enum definitions for more information.
+	       information. See enum definitions for more information:
-		- \c B_UPDATE_MIME_INFO_NO_FORCE
+	       - \c B_UPDATE_MIME_INFO_NO_FORCE
-		- \c B_UPDATE_MIME_INFO_FORCE_KEEP_TYPE
+	       - \c B_UPDATE_MIME_INFO_FORCE_KEEP_TYPE
-		- \c B_UPDATE_MIME_INFO_FORCE_UPDATE_ALL
+	       - \c B_UPDATE_MIME_INFO_FORCE_UPDATE_ALL
 
-	\returns A status code. \c B_OK if everything went fine, an error code
+	\return A status code, \c B_OK if everything went fine, an error code
-		otherwise.
+	        otherwise.
+
+	\since BeOS R3
 */
 
 
 /*!
-	\fn status_t create_app_meta_mime(const char *path, int recursive,
+	\fn status_t create_app_meta_mime(const char* path, int recursive,
 		int synchronous, int force)
 	\brief Creates a MIME database entry for one or more applications.
 
@@ -105,65 +116,128 @@
 	\param path The path to an application file, a directory, or \c NULL.
 	\param recursive Trigger recursive behavior if not \c NULL.
 	\param synchronous Waits until the operation is finished if not \c NULL,
-		otherwise it returns immediately and the operation is done
+	       otherwise it returns immediately and the operation is done
-		asynchronously.
+	       asynchronously.
 	\param force Entries are created even if they do already exist if not
-		\c NULL.
+	       \c NULL.
 
-	\returns A status code. \c B_OK if everything went fine, an error code
+	\return A status code, \c B_OK if everything went fine, an error code
-		otherwise.
+	        otherwise.
+
+	\since BeOS R3
 */
 
 
 /*!
-	\fn status_t get_device_icon(const char *device, void *icon, int32 size)
+	\fn status_t get_device_icon(const char* device, void* icon, int32 size)
 	\brief Retrieves an icon associated with a given device.
 
 	\param device The path to the device.
 	\param icon A pointer to a buffer the icon data shall be written to.
 	\param size The size of the icon to retrieve. Currently 16
-		(\c B_MINI_ICON) and 32 (\c B_LARGE_ICON) are supported.
+	       (\c B_MINI_ICON) and 32 (\c B_LARGE_ICON) are supported.
 
-	\returns A status code.
+	\return A status code, \c B_OK if everything went fine, an error code
-	\retval B_OK Everything went fine.
+	        otherwise.
+	\retval B_OK Retrieved the icon successfully.
 	\retval B_BAD_VALUE \a device or \a icon was \c NULL.
 	\retval B_NO_MEMORY Ran out of memory allocating bitmap.
+
+	\since BeOS R3
 */
 
 
 /*!
-	\fn status_t get_device_icon(const char *device, BBitmap *icon,
+	\fn status_t get_device_icon(const char* device, BBitmap* icon,
 		icon_size which)
-	\brief Retrieves an icon associated with a given device into a BBitmap.
+	\brief Retrieves an icon associated with a given device into a BBitmap,
+	       C++ only.
 
 	\param device The path to the device.
 	\param icon A pointer to a pre-allocated BBitmap of the correct dimension
-		   to store the requested icon (16x16 for the mini and 32x32 for the
+	       to store the requested icon (16x16 for the mini and 32x32 for the
-		   large icon).
+	       large icon).
 	\param which The size of the icon to retrieve. Currently 16
-		(\c B_MINI_ICON) and 32 (\c B_LARGE_ICON) are supported.
+	       (\c B_MINI_ICON) and 32 (\c B_LARGE_ICON) are supported.
 
-	\returns A status code. \c B_OK if everything went fine, an error code
+	\return A status code, \c B_OK if everything went fine, an error code
-		otherwise.
+	        otherwise.
+	\retval B_OK Retrieved the icon successfully.
+	\retval B_BAD_VALUE \a device or \a icon was \c NULL.
+
+	\since Haiku R1
 */
 
 
 /*!
 	\fn status_t get_device_icon(const char* device, uint8** _data,
 		size_t* _size, type_code* _type);
-	\brief Undocumented.
+	\brief Try to get the icon by name first, if that fails try to get the
+	       vector icon, C++ only.
+
+	\param device The path to the device.
+	\param _data A pointer to a pointer to an array of uint8 pixel data to
+	       fill out.
+	\param _size The size of the icon to fill out. If vector, it is filled in
+	       with the width in pixels, if bitmap, one of the following constants:
+	       - \c B_MINI_ICON
+	       - \c B_LARGE_ICON
+	\param _type The icon type code to fill out, one of the following:
+	       - \c B_MINI_ICON_TYPE
+	       - \c B_LARGE_ICON_TYPE
+	       - \c B_VECTOR_ICON_TYPE
+
+	\return A status code, \c B_OK if everything went fine, an error code
+	        otherwise.
+	\retval B_OK Retrieved the icon successfully.
+	\retval B_BAD_VALUE \a device, \a _data, \a _size, or _type was \c NULL.
+
+	\since Haiku R1
 */
 
 
 /*!
 	\fn status_t get_named_icon(const char* name, BBitmap* icon,
 		icon_size which);
-	\brief Undocumented.
+	\brief Get the icon by name, C++ only.
+
+	\param name The name of the icon to get.
+	\param icon A pointer to a pre-allocated BBitmap of the correct dimension
+	       to store the requested icon (16x16 for the mini and 32x32 for the
+	       large icon).
+	\param which The size of the icon to retrieve. Currently 16
+	       (\c B_MINI_ICON) and 32 (\c B_LARGE_ICON) are supported.
+
+	\return A status code, \c B_OK if everything went fine, an error code
+	        otherwise.
+	\retval B_OK Retrieved the icon successfully.
+	\retval B_BAD_VALUE \a name or \a icon was \c NULL.
+
+	\since Haiku R1
 */
 
 
 /*!
-	\fn status_t get_named_icon(const char* name, uint8** _data, 
+	\fn status_t get_named_icon(const char* name, uint8** _data,
 		size_t* _size, type_code* _type);
-	\brief Undocumented.
+	\brief Get the icon by name, C++ only.
+
+	\param name The name of the icon to get.
+	\param _data A pointer to a pointer to an array of uint8 pixel data to
+	       fill out.
+	\param _size The size of the icon to fill out. If vector, it is filled in
+	       with the width in pixels, if bitmap, one of the following constants:
+	       - \c B_MINI_ICON
+	       - \c B_LARGE_ICON
+	\param _type The icon type code to fill out, one of the following:
+	       - \c B_MINI_ICON_TYPE
+	       - \c B_LARGE_ICON_TYPE
+	       - \c B_VECTOR_ICON_TYPE
+
+	\return A status code, \c B_OK if everything went fine, an error code
+	        otherwise.
+	\retval B_OK Retrieved the icon successfully.
+	\retval B_BAD_VALUE \a name, \a _data, \a _size, or \c _type was \c NULL.
+
+	\since Haiku R1
 */

docs/user/storage/Node.dox

@@ -1,15 +1,14 @@
 /*
- * Copyright 2002-2011 Haiku Inc. All rights reserved.
+ * Copyright 2002-2014 Haiku, Inc. All rights reserved.
  * Distributed under the terms of the MIT License.
  *
  * Authors:
- *		Tyler Dauwalder, [email protected]
  *		John Scipione, [email protected]
  *		Ingo Weinhold, [email protected]
  *
  * Corresponds to:
- *		headers/os/storage/Node.h	rev 42803
+ *		headers/os/storage/Node.h	hrev47402
- *		src/kits/storage/Node.cpp	rev 42803
+ *		src/kits/storage/Node.cpp	hrev47402
  */
 
 
@@ -17,7 +16,7 @@
 	\file Node.h
 	\ingroup storage
 	\ingroup libbe
-	\brief Provides the BNode class and node_ref structure.
+	\brief Provides the BNode class and node_ref struct.
 */
 
 
@@ -26,50 +25,102 @@
 	\ingroup storage
 	\ingroup libbe
 	\brief Reference structure to a particular vnode on a device.
+
+	\since BeOS R3
 */
 
 
 /*!
 	\fn node_ref::node_ref()
 	\brief Creates an uninitialized node_ref object.
+
+	\since BeOS R3
 */
 
 
 /*!
-	\fn node_ref::node_ref(const node_ref &ref)
+	\fn node_ref::node_ref(const node_ref& other)
 	\brief Creates a copy of the given node_ref object.
 
-	\param ref the node_ref to be copied.
+	\param other the node_ref to be copied.
+
+	\since BeOS R3
 */
 
 
 /*!
-	\fn bool node_ref::operator==(const node_ref &ref) const
+	\name Operators
+*/
+
+
+//! @{
+
+
+/*!
+	\fn bool node_ref::operator==(const node_ref& other) const
 	\brief Tests whether this node_ref and the supplied one are equal.
 
-	\param ref the node_ref to be compared with.
+	\param other The node_ref to be compared against.
 
 	\return \c true, if the objects are equal, \c false otherwise.
+
+	\since BeOS R3
 */
 
 
 /*!
-	\fn bool node_ref::operator!=(const node_ref &ref) const
+	\fn bool node_ref::operator!=(const node_ref& other) const
-	\brief Tests whether this node_ref and the supplied one are not equal.
+	\brief Tests whether this node_ref and the supplied one are NOT equal.
 
-	\param ref the node_ref to be compared with.
+	\param other The node_ref to be compared against.
 
-	\return \c true, if the objects are \b not equal, \c false otherwise.
+	\return \c true, if the objects are \b NOT equal, \c false otherwise.
+
+	\since BeOS R3
 */
 
 
 /*!
-	\fn node_ref& node_ref::operator=(const node_ref &ref)
+	\fn bool node_ref::operator<(const node_ref& other) const
+	\brief Tests whether this node_ref is less than the supplied one.
+
+	\param other The node_ref to be compared against.
+
+	\return \c true, if this node_ref is less than \a other,
+	        \c false otherwise.
+
+	\since Haiku R1
+*/
+
+
+/*!
+	\fn node_ref& node_ref::operator=(const node_ref& other)
 	\brief Makes this node ref a copy of the supplied one.
 
-	\param ref the node_ref to be copied.
+	\param other The node_ref to be copied.
 
-	\return a reference to this object.
+	\return A reference to this object.
+
+	\since BeOS R3
+*/
+
+
+//! @}
+
+
+/*!
+	\var node_ref::device
+	\brief The device number on which the node is located.
+
+	\since BeOS R3
+*/
+
+
+/*!
+	\var node_ref::node
+	\brief The node's inode number.
+
+	\since BeOS R3
 */
 
 
@@ -83,107 +134,96 @@
 	attributes belonging to filesystem entries. The BNode is unaware of the
 	name that refers to it in the filesystem (i.e. its entry), instead, a
 	BNode is concerned solely with the entry's data and attributes.
-*/
 
-
+	\since BeOS R3
-/*!
-	\var BNode::fFd
-
-	File descriptor for the given node.
-*/
-
-
-/*!
-	\var BNode::fAttrFd
-
-	File descriptor for the attribute directory of the node.
-	Initialized lazily.
-*/
-
-
-/*!
-	\var BNode::fCStatus
-
-	The object's initialization status.
 */
 
 
 /*!
 	\fn BNode::BNode()
 	\brief Creates an uninitialized BNode object.
+
+	\see SetTo()
+
+	\since BeOS R3
 */
 
 
 /*!
-	\fn BNode::BNode(const entry_ref *ref)
+	\fn BNode::BNode(const entry_ref* ref)
 	\brief Creates a BNode object and initializes it to the specified
-		entry_ref.
+	       entry_ref.
 
-	\param ref the entry_ref referring to the entry.
+	\param ref The entry_ref referring to the node.
+
+	\since BeOS R3
 */
 
 
 /*!
-	\fn BNode::BNode(const BEntry *entry)
+	\fn BNode::BNode(const BEntry* entry)
 	\brief Creates a BNode object and initializes it to the specified
-		filesystem entry.
+	       filesystem entry.
 
-	\param entry the BEntry representing the entry.
+	\param entry The BEntry referring to the node.
+
+	\since BeOS R3
 */
 
 
 /*!
-	\fn BNode::BNode(const char *path)
+	\fn BNode::BNode(const char* path)
 	\brief Creates a BNode object and initializes it to the entry referred
-		to by the specified path.
+	       to by the specified path.
 
-	\param path the path referring to the entry.
+	\param path The \a path referring to the node.
+
+	\since BeOS R3
 */
 
 
 /*!
-	\fn BNode::BNode(const BDirectory *dir, const char *path)
+	\fn BNode::BNode(const BDirectory* dir, const char* path)
 	\brief Creates a BNode object and initializes it to the entry referred
-		to by the specified path rooted in the specified directory.
+	       to by the specified path rooted in the specified directory.
 
-	\param dir the BDirectory, relative to which the entry's path name is
+	\param dir The base BDirectory.
-		given.
+	\param path The \a path name relative to \a dir.
-	\param path the entry's path name relative to \a dir.
+
+	\since BeOS R3
 */
 
 
 /*!
-	\fn BNode::BNode(const BNode &node)
+	\fn BNode::BNode(const BNode& other)
 	\brief Creates a copy of the given BNode.
 
-	\param node the BNode to be copied.
+	\param other The BNode to be copied.
+
+	\since BeOS R3
 */
 
 
 /*!
 	\fn BNode::~BNode()
 	\brief Frees all resources associated with the BNode.
+
+	\since BeOS R3
 */
 
 
 /*!
-	\fn status_t BNode::InitCheck() const
+	\fn status_t BNode::GetStat(struct stat* stat) const
-	\brief Checks whether the object has been properly initialized or not.
-	
-	\returns B_OK if the object has been properly initialized, or an error
-		code otherwise.
-*/
-
-
-/*!
-	\fn status_t BNode::GetStat(struct stat *st) const
 	\brief Fills in the given stat structure with the <tt>stat()</tt>
-		information for this object.
+	       information for this object.
 
-	\param st a pointer to a stat structure to be filled in.
+	\param stat A pointer to a stat structure to be filled in.
 
+	\return \c B_OK on success or an error code otherwise.
 	\retval B_OK Everything went fine.
-	\retval B_BAD_VALUE: \c NULL \a st.
+	\retval B_BAD_VALUE: \c NULL \a stat.
+
+	\since Haiku R1
 */
 
 
@@ -194,12 +234,14 @@
 	Remember to call close() on the file descriptor when you're through
 	with it.
 
-	\returns a valid file descriptor, or -1 if something went wrong.
+	\returns A valid file descriptor, or -1 if something went wrong.
+
+	\since Haiku R1
 */
 
 
 /*!
-	\name Assignment Methods
+	\name Constructor Helpers
 */
 
 
@@ -207,59 +249,89 @@
 
 
 /*!
-	\fn BNode& BNode::operator=(const BNode &node)
+	\fn status_t BNode::InitCheck() const
-	\brief Initializes the object as a copy of the \a node.
+	\brief Checks whether the object has been properly initialized or not.
 
-	\param node the BNode to be copied.
+	\returns \c B_OK if the object has been properly initialized, or
+	         \c B_NO_INIT otherwise.
 
-	\returns a reference to this BNode object.
+	\since BeOS R3
 */
 
 
 /*!
-	\fn status_t BNode::SetTo(const entry_ref *ref)
+	\fn status_t BNode::SetTo(const entry_ref* ref)
 	\brief Initializes the object to the specified entry_ref.
 
-	\param ref the entry_ref referring to the entry.
+	\param ref The entry_ref referring to the entry.
 
+	\return \c B_OK on success or an error code otherwise.
 	\retval B_OK: Everything went fine.
-	\retval B_BAD_VALUE: \c NULL \a ref.
+	\retval B_BAD_VALUE: \a ref was \c NULL.
 	\retval B_ENTRY_NOT_FOUND: The entry could not be found.
-	\retval B_BUSY: The entry is locked.
+	\retval B_BUSY: The entry was locked.
+
+	\since BeOS R3
 */
 
 
 /*!
-	\fn status_t BNode::SetTo(const BEntry *entry)
+	\fn status_t BNode::SetTo(const BEntry* entry)
 	\brief Initializes the object to the specified filesystem \a entry.
 
-	\param entry the BEntry representing the entry.
+	\param entry The BEntry representing the entry.
 
+	\return \c B_OK on success or an error code otherwise.
 	\retval B_OK Everything went fine.
-	\retval B_BAD_VALUE \c NULL \a entry.
+	\retval B_BAD_VALUE \a entry was \c NULL.
-	\retval B_ENTRY_NOT_FOUND The entry could not be found.
+	\retval B_ENTRY_NOT_FOUND The \a entry could not be found.
-	\retval B_BUSY The entry is locked.
+	\retval B_BUSY The \a entry was locked.
+
+	\since BeOS R3
 */
 
 
 /*!
-	\fn status_t BNode::SetTo(const BDirectory *dir, const char *path)
+	\fn status_t BNode::SetTo(const char* path)
-	\brief Initializes the object to the entry referred by the
+	\brief Initializes the object to the specified \a path.
-		specified \a path relative to the the specified directory.
 
-	\param dir the base BDirectory.
+	\param path The entry's path name; \a path can be relative or absolute,
-	\param path the entry's path name relative to \a dir
+	       and can contain "." and ".." elements. If path is relative, it uses
+	       the current working directory as the base directory.
 
+	\return \c B_OK on success or an error code otherwise.
 	\retval B_OK Everything went fine.
-	\retval B_BAD_VALUE \c NULL \a entry.
+	\retval B_BAD_VALUE \a path was \c NULL.
 	\retval B_ENTRY_NOT_FOUND The entry could not be found.
-	\retval B_BUSY The entry is locked.
+	\retval B_BUSY The entry of was locked.
+
+	\since BeOS R3
+*/
+
+
+/*!
+	\fn status_t BNode::SetTo(const BDirectory* dir, const char* path)
+	\brief Initializes the object to the entry referred by the
+	       specified \a path relative to the the specified directory.
+
+	\param dir The base BDirectory.
+	\param path The path name relative to \a dir.
+
+	\return \c B_OK on success or an error code otherwise.
+	\retval B_OK Everything went fine.
+	\retval B_BAD_VALUE \a dir was \c NULL.
+	\retval B_ENTRY_NOT_FOUND The entry could not be found.
+	\retval B_BUSY The entry was locked.
+
+	\since BeOS R3
 */
 
 
 /*!
 	\fn void BNode::Unset()
 	\brief Returns the object to an uninitialized state.
+
+	\since BeOS R3
 */
 
 
@@ -277,11 +349,14 @@
 /*!
 	\fn status_t BNode::Lock()
 	\brief Attains an exclusive lock on the data referred to by this node
-		so that it may not be modified by any other objects or methods.
+	       so that it may not be modified by any other objects or methods.
 
+	\return \c B_OK on success or an error code otherwise.
 	\retval B_OK Everything went fine.
 	\retval B_FILE_ERROR The object is not initialized.
 	\retval B_BUSY The node is already locked.
+
+	\since BeOS R3
 */
 
 
@@ -289,9 +364,12 @@
 	\fn status_t BNode::Unlock()
 	\brief Unlocks the date referred to by this node.
 
+	\return \c B_OK on success or an error code otherwise.
 	\retval B_OK Everything went fine.
 	\retval B_FILE_ERROR The object is not initialized.
 	\retval B_BAD_VALUE The node is not locked.
+
+	\since BeOS R3
 */
 
 
@@ -299,8 +377,11 @@
 	\fn status_t BNode::Sync()
 	\brief Immediately performs any pending disk actions on the node.
 
+	\return \c B_OK on success or an error code otherwise.
 	\retval B_OK Everything went fine.
 	\retval B_FILE_ERROR Something went wrong.
+
+	\since BeOS R3
 */
 
 
@@ -316,163 +397,192 @@
 
 
 /*!
-	\fn ssize_t BNode::WriteAttr(const char *attr, type_code type,
+	\fn ssize_t BNode::WriteAttr(const char* attr, type_code type,
-								 off_t offset, const void *buffer, size_t len)
+		off_t offset, const void* buffer, size_t length)
 	\brief Writes data from a buffer to an attribute.
 
-	Write \a len bytes of data from \a buffer to the attribute specified
+	Write \a length bytes of data from \a buffer to the attribute specified
 	by \a name after erasing any data that existed previously. The type
 	specified by \a type \em is remembered, and may be queried with
 	GetAttrInfo(). The value of \a offset is currently ignored.
 
-	\param attr the name of the attribute.
+	\param attr The name of the attribute.
-	\param type the type of the attribute.
+	\param type The type of the attribute.
-	\param offset the index at which to write the data (currently ignored).
+	\param offset The index at which to write the data (currently ignored).
-	\param buffer the buffer containing the data to be written.
+	\param buffer The buffer containing the data to be written.
-	\param len the number of bytes to be written.
+	\param length The number of bytes to be written.
 
-	\returns the number of bytes actually written.
+	\return The number of bytes actually written.
-	\retval B_BAD_VALUE \a attr or \a buffer is \c NULL.
+	\retval B_BAD_VALUE \a attr or \a buffer was \c NULL.
-	\retval B_FILE_ERROR The object is not initialized or the node it refers to
+	\retval B_FILE_ERROR The object was not initialized or the node it refers
-		is read only.
+	        to was read only.
 	\retval B_NOT_ALLOWED The node resides on a read only volume.
-	\retval B_DEVICE_FULL Insufficient disk space.
+	\retval B_DEVICE_FULL There was insufficient disk space to complete the
-	\retval B_NO_MEMORY Insufficient memory to complete the operation.
+	        operation.
+	\retval B_NO_MEMORY There was insufficient memory to complete the
+	        operation.
+
+	\since BeOS R3
 */
 
 
 /*!
-	\fn ssize_t BNode::ReadAttr(const char *attr, type_code type,
+	\fn ssize_t BNode::ReadAttr(const char* attr, type_code type,
-								off_t offset, void *buffer, size_t len) const
+		off_t offset, void* buffer, size_t length) const
 	\brief Reads data from an attribute into \a buffer.
 
-	Reads \a len bytes of data from the attribute given by \a name into
+	Reads \a length bytes of data from the attribute given by \a name into
 	\a buffer. \a type and \a offset are currently ignored.
 
-	\param attr the name of the attribute.
+	\param attr The name of the attribute.
-	\param type the type of the attribute (currently ignored).
+	\param type The type of the attribute (currently ignored).
-	\param offset the index from which to read the data (currently ignored).
+	\param offset The index from which to read the data (currently ignored).
-	\param buffer the buffer for the data to be read.
+	\param buffer The buffer for the data to be read.
-	\param len the number of bytes to be read.
+	\param length The number of bytes to be read.
 
-	\returns the number of bytes actually read
+	\return The number of bytes actually read.
-	\retval B_BAD_VALUE \a attr or \a buffer is \c NULL.
+	\retval B_BAD_VALUE \a attr or \a buffer was \c NULL.
-	\retval B_FILE_ERROR The object is not initialized.
+	\retval B_FILE_ERROR The object was not initialized.
-	\retval B_ENTRY_NOT_FOUND The node has no attribute \a attr.
+	\retval B_ENTRY_NOT_FOUND The node had no attribute \a attr.
+
+	\since BeOS R3
 */
 
 
 /*!
-	\fn status_t BNode::RemoveAttr(const char *name)
+	\fn status_t BNode::RemoveAttr(const char* name)
 	\brief Deletes the attribute given by \a name.
 
-	\param name the name of the attribute to remove.
+	\param name The name of the attribute to remove.
 
+	\return \c B_OK on success or an error code otherwise.
 	\retval B_OK Everything went fine.
-	\retval B_BAD_VALUE \a name is \c NULL.
+	\retval B_BAD_VALUE \a name was \c NULL.
-	\retval B_FILE_ERROR The object is not initialized or the node it
+	\retval B_FILE_ERROR The object was not initialized or the node it
-		refers to read only.
+	        referred to was read-only.
-	\retval B_ENTRY_NOT_FOUND The node has no attribute \a name.
+	\retval B_ENTRY_NOT_FOUND The node had no attribute \a name.
-	\retval B_NOT_ALLOWED The node resides on a read only volume.
+	\retval B_NOT_ALLOWED The node resided on a read-only volume.
+
+	\since BeOS R3
 */
 
 
 /*!
-	\fn status_t BNode::RenameAttr(const char *oldname, const char *newname)
+	\fn status_t BNode::RenameAttr(const char* oldName, const char* newName)
-	\brief Moves the attribute given by \a oldname to \a newname.
+	\brief Moves the attribute given by \a oldName to \a newName.
 
-	If \a newname already exists, the data is clobbered.
+	If \a newName already exists, the data is clobbered.
 
-	\param oldname the name of the attribute to be renamed.
+	\param oldName The name of the attribute to be renamed.
-	\param newname the new name for the attribute.
+	\param newName The new name for the attribute.
 
+	\return \c B_OK on success or an error code otherwise.
 	\retval B_OK Everything went fine.
-	\retval B_BAD_VALUE \a oldname or \a newname is \c NULL.
+	\retval B_BAD_VALUE \a oldName or \a newName was \c NULL.
-	\retval B_FILE_ERROR The object is not initialized or the node it
+	\retval B_FILE_ERROR The object was not initialized or the node it
-		refers to is read only.
+	        referred to was read only.
-	\retval B_ENTRY_NOT_FOUND The node has no attribute \a oldname.
+	\retval B_ENTRY_NOT_FOUND The node had no attribute \a oldName.
-	\retval B_NOT_ALLOWED The node resides on a read only volume.
+	\retval B_NOT_ALLOWED The node resided on a read-only volume.
+
+	\since BeOS R3
 */
 
 
 /*!
-	\fn status_t BNode::GetAttrInfo(const char *name,
+	\fn status_t BNode::GetAttrInfo(const char* name,
-									struct attr_info *info) const
+		struct attr_info* info) const
 	\brief Fills in the pre-allocated attr_info struct pointed to by \a info
-		with information about the attribute specified by \a name.
+	       with information about the attribute specified by \a name.
 
-	\param name the name of the attribute
+	\param name The name of the attribute.
-	\param info the attr_info structure to be filled in
+	\param info The attr_info structure to be filled in.
 
+	\return \c B_OK on success or an error code otherwise.
 	\retval B_OK Everything went fine.
-	\retval B_BAD_VALUE \a name is \c NULL.
+	\retval B_BAD_VALUE \a name was \c NULL.
-	\retval B_FILE_ERROR The object is not initialized.
+	\retval B_FILE_ERROR The object was not initialized.
-	\retval B_ENTRY_NOT_FOUND The node has no attribute \a name.
+	\retval B_ENTRY_NOT_FOUND The node had no attribute \a name.
+
+	\since BeOS R3
 */
 
 
 /*!
-	\fn status_t BNode::GetNextAttrName(char *buffer)
+	\fn status_t BNode::GetNextAttrName(char* buffer)
 	\brief Copies the name of the attribute into \c buffer and then advances
-		the pointer to the next attribute.
+	       the pointer to the next attribute.
 
 	The name of the node is first copied into \a buffer, which should be at
 	least \c B_ATTR_NAME_LENGTH characters long. The copied node name is
-	\c NUL terminated. Once the name is copied the attribute list pointer
+	\0 terminated. Once the name is copied the attribute list pointer
 	is advanced to the next attribute in the list. When GetNextAttrName()
 	reaches the end of the list it returns \c B_ENTRY_NOT_FOUND.
 
 	\param buffer A buffer to copy the name of the attribute into.
 
+	\return \c B_OK on success or an error code otherwise.
 	\retval B_OK The Attribute name was copied and there are more attribute
-		names to copy.
+	        names to copy.
-	\retval B_BAD_VALUE passed in \a buffer is \c NULL.
+	\retval B_BAD_VALUE passed in \a buffer was \c NULL.
-	\retval B_FILE_ERROR The object is not initialized.
+	\retval B_FILE_ERROR The object was not initialized.
-	\retval B_ENTRY_NOT_FOUND There are no more attributes, the last attribute
+	\retval B_ENTRY_NOT_FOUND There were no more attributes, the last attribute
-		name has already been copied.
+	        name had already been copied.
+
+	\since BeOS R3
 */
 
 
 /*!
 	\fn status_t BNode::RewindAttrs()
 	\brief Resets the object's attribute pointer to the first attribute in the
-		list.
+	       list.
 
+	\return \c B_OK on success or an error code otherwise.
 	\retval B_OK Everything went fine.
 	\retval B_FILE_ERROR Some other error occurred.
+
+	\since BeOS R3
 */
 
 
 /*!
-	\fn status_t BNode::WriteAttrString(const char *name, const BString *data)
+	\fn status_t BNode::WriteAttrString(const char* name, const BString* data)
 	\brief Writes the specified string to the specified attribute, clobbering
-		any previous data.
+	       any previous data.
 
 	\param name the name of the attribute.
 	\param data the BString to be written to the attribute.
 
+	\return \c B_OK on success or an error code otherwise.
 	\retval B_OK Everything went fine.
-	\retval B_BAD_VALUE \c NULL \a name or \a data
+	\retval B_BAD_VALUE \a name or \a data was \c NULL.
-	\retval B_FILE_ERROR The object is not initialized or the node it refers to
+	\retval B_FILE_ERROR The object was not initialized or the node it
-		is read only.
+	        referred to was read-only.
-	\retval B_NOT_ALLOWED The node resides on a read only volume.
+	\retval B_NOT_ALLOWED The node resided on a read-only volume.
-	\retval B_DEVICE_FULL Insufficient disk space.
+	\retval B_DEVICE_FULL There was insufficient disk space to complete the
-	\retval B_NO_MEMORY Insufficient memory to complete the operation.
+	        operation.
+	\retval B_NO_MEMORY There was insufficient memory to complete the
+	        operation.
+
+	\since Haiku R1
 */
 
 
 /*!
-	\fn status_t BNode::ReadAttrString(const char *name, BString *result) const
+	\fn status_t BNode::ReadAttrString(const char* name, BString* result) const
 	\brief Reads the data of the specified attribute into the pre-allocated
-		\a result.
+	       \a result.
 
 	\param name the name of the attribute.
 	\param result the BString to be set to the value of the attribute.
 
+	\return \c B_OK on success or an error code otherwise.
 	\retval B_OK Everything went fine.
-	\retval B_BAD_VALUE \a name or \a result is \c NULL.
+	\retval B_BAD_VALUE \a name or \a result was \c NULL.
-	\retval B_FILE_ERROR The object is not initialized.
+	\retval B_FILE_ERROR The object was not initialized.
-	\retval B_ENTRY_NOT_FOUND The node has no attribute \a attr.
+	\retval B_ENTRY_NOT_FOUND The node had no attribute \a attr.
+
+	\since Haiku R1
 */
 
 
@@ -480,23 +590,37 @@
 
 
 /*!
-	\name Comparison Methods
+	\name Operators
 */
 
 
 //! @{
 
 
+/*!
+	\fn BNode& BNode::operator=(const BNode& other)
+	\brief Initializes the object as a copy of \a other.
+
+	\param other the BNode to be copied.
+
+	\returns A reference to this BNode object.
+
+	\since BeOS R3
+*/
+
+
 /*!
 	\fn bool BNode::operator==(const BNode &node) const
 	\brief Tests whether this and the supplied BNode object are equal.
 
 	Two BNode objects are said to be equal if they're set to the same node,
-	or if they're both \c B_NO_INIT.
+	or if they're both unintialized
 
-	\param node the BNode to be compared with.
+	\param node The BNode to be compared against.
 
 	\return \c true, if the BNode objects are equal, \c false otherwise.
+
+	\since BeOS R3
 */
 
 
@@ -505,139 +629,13 @@
 	\brief Tests whether this and the supplied BNode object are not equal.
 
 	Two BNode objects are said to be equal if they're set to the same node,
-	or if they're both \c B_NO_INIT.
+	or if they're both unintialized.
 
-	\param node the BNode to be compared with
+	\param node The BNode to be compared with
 
 	\return \c false, if the BNode objects are equal, \c true otherwise.
-*/
+
-
+	\since BeOS R3
-
-//! @}
-
-
-/*!
-	\name Private Methods
-*/
-
-
-//! @{
-
-
-/*!
-	\fn status_t BNode::set_fd(int fd)
-	\brief Sets the node's file descriptor.
-
-	Used by each implementation (i.e. BNode, BFile, BDirectory, etc.) to set
-	the node's file descriptor. This allows each subclass to use the various
-	file-type specific system calls for opening file descriptors.
-
-	\note This method calls close_fd() to close previously opened FDs. Thus
-		derived classes should take care to first call set_fd() and set
-		class specific resources freed in their close_fd() version
-		thereafter.
-
-	\param fd the file descriptor this BNode should be set to (may be -1).
-
-	\returns \c B_OK if everything went fine, or an error code if something
-		went wrong.
-*/
-
-
-/*!
-	\fn void BNode::close_fd()
-	\brief Closes the node's file descriptor(s).
-
-	To be implemented by subclasses to close the file descriptor using the
-	proper system call for the given file-type. This implementation calls
-	_kern_close(fFd) and also _kern_close(fAttrDir) if necessary.
-*/
-
-
-/*!
-	\fn void BNode::set_status(status_t newStatus)
-	\brief Sets the BNode's status.
-
-	To be used by derived classes instead of accessing the BNode's private
-	\c fCStatus member directly.
-
-	\param newStatus the new value for the status variable.
-*/
-
-
-/*!
-	\fn status_t BNode::_SetTo(int fd, const char *path, bool traverse)
-	\brief Initializes the BNode's file descriptor to the node referred to
-		 by the given FD and path combo.
-
-	\a path must either be \c NULL, an absolute or a relative path.
-	In the first case, \a fd must not be \c NULL; the node it refers to will
-	be opened. If absolute, \a fd is ignored. If relative and \a fd is >= 0,
-	it will be reckoned off the directory identified by \a fd, otherwise off
-	the current working directory.
-
-	The method will first try to open the node with read and write permission.
-	If that fails due to a read-only FS or because the user has no write
-	permission for the node, it will re-try opening the node read-only.
-
-	The \a fCStatus member will be set to the return value of this method.
-
-	\param fd Either a directory FD or a value < 0. In the latter case \a path
-		   must be specified.
-	\param path Either \a NULL in which case \a fd must be given, absolute, or
-		   relative to the directory specified by \a fd (if given) or to the
-		   current working directory.
-	\param traverse If the node identified by \a fd and \a path is a symlink
-		   and \a traverse is \c true, the symlink will be resolved recursively.
-
-	\returns \c B_OK if everything went fine, or an error code if something
-		went wrong.
-*/
-
-
-/*!
-	\fn status_t BNode::_SetTo(const entry_ref *ref, bool traverse)
-	\brief Initializes the BNode's file descriptor to the node referred to
-		 by the given entry_ref.
-
-	The method will first try to open the node with read and write permission.
-	If that fails due to a read-only FS or because the user has no write
-	permission for the node, it will re-try opening the node read-only.
-
-	The \a fCStatus member will be set to the return value of this method.
-
-	\param ref An entry_ref identifying the node to be opened.
-	\param traverse If the node identified by \a ref is a symlink and
-		\a traverse is \c true, the symlink will be resolved recursively.
-
-	\returns \c B_OK if everything went fine, or an error code if something
-		went wrong.
-*/
-
-
-/*!
-	\fn status_t BNode::set_stat(struct stat &st, uint32 what)
-	\brief Modifies a certain setting for this node based on \a what and the
-		corresponding value in \a st.
-
-	Inherited from and called by BStatable.
-
-	\param st a stat structure containing the value to be set.
-	\param what specifies what setting to be modified.
-
-	\returns \c B_OK if everything went fine, or an error code if something
-		went wrong.
-*/
-
-
-/*!
-	\fn status_t BNode::InitAttrDir()
-	\brief Verifies that the BNode has been properly initialized, and then
-		(if necessary) opens the attribute directory on the node's file
-		descriptor, storing it in fAttrDir.
-
-	\returns \c B_OK if everything went fine, or an error code if something
-		went wrong.
 */
 
 

docs/user/storage/NodeInfo.dox

@@ -1,5 +1,5 @@
 /*
- * Copyright 2013 Haiku Inc. All rights reserved.
+ * Copyright 2013-2014 Haiku, Inc. All rights reserved.
  * Distributed under the terms of the MIT License.
  *
  * Authors:
@@ -8,8 +8,8 @@
  *		Ingo Weinhold, [email protected]
  *
  * Corresponds to:
- *		headers/os/storage/NodeInfo.h	hrev45253
+ *		headers/os/storage/NodeInfo.h	hrev47402
- *		src/kits/storage/NodeInfo.cpp	hrev45253
+ *		src/kits/storage/NodeInfo.cpp	hrev47402
  */
 
 
@@ -30,6 +30,8 @@
 	BNodeInfo provides a nice wrapper to all sorts of useful meta data such as
 	the MIME-type, the file's icon and the application that will open
 	the file.
+
+	\since BeOS R3
 */
 
 
@@ -39,16 +41,20 @@
 
 	After created a BNodeInfo with this, you should call SetTo().
 
-	\see SetTo(BNode *node)
+	\see SetTo(BNode* node)
+
+	\since BeOS R3
 */
 
 
 /*!
-	\fn BNodeInfo::BNodeInfo(BNode *node)
+	\fn BNodeInfo::BNodeInfo(BNode* node)
 	\brief Creates a BNodeInfo object and initializes it to the supplied
 	       \a node.
 
-	\param node The \a node to gather information on.
+	\param node The \a node to initialize to and gather information.
+
+	\since BeOS R3
 */
 
 
@@ -57,6 +63,8 @@
 	\brief Frees the object and associated resources.
 
 	The internal BNode object is not deleted.
+
+	\since BeOS R3
 */
 
 
@@ -69,7 +77,7 @@
 
 
 /*!
-	\fn status_t BNodeInfo::SetTo(BNode *node)
+	\fn status_t BNodeInfo::SetTo(BNode* node)
 	\brief Initializes the BNodeInfo to the supplied \a node.
 
 	The BNodeInfo object does not copy the supplied \a node object, it uses it
@@ -82,6 +90,8 @@
 	\returns A status code.
 	\retval B_OK Everything went fine.
 	\retval B_BAD_VALUE The node was not properly initialized.
+
+	\since BeOS R3
 */
 
 
@@ -92,6 +102,8 @@
 	\returns A status code.
 	\retval B_OK The object was properly initialized.
 	\retval B_BAD_VALUE The object was \b not properly initialized.
+
+	\since BeOS R3
 */
 
 
@@ -107,7 +119,7 @@
 
 
 /*!
-	\fn status_t BNodeInfo::GetType(char *type) const
+	\fn status_t BNodeInfo::GetType(char* type) const
 	\brief Writes the MIME-type of the node into \a type.
 
 	The source of the type information is the \c BEOS:TYPE attribute of the
@@ -125,18 +137,20 @@
 	        attribute is longer than \c B_MIME_TYPE_LENGTH.
 	\retval B_BAD_TYPE The stored type string attribute has the wrong type.
 	\retval B_ENTRY_NOT_FOUND No type is set on the node.
+
+	\since BeOS R3
 */
 
 
 /*!
-	\fn status_t BNodeInfo::SetType(const char *type)
+	\fn status_t BNodeInfo::SetType(const char* type)
 	\brief Sets the MIME-type of the node. If \a type is \c NULL the
 	       \c BEOS:TYPE attribute is removed instead.
 
 	The \a type string is written into the \c BEOS:TYPE attribute of the node.
 	If \a type is \c NULL, the \c BEOS:TYPE attribute is removed instead. The
 	\a type parameter may not by longer than \c B_MIME_TYPE_LENGTH in length
-	including the terminating \c NUL character.
+	including the terminating \0 character.
 
 	\param type The MIME-type to be assigned to the \a node. Must not be
 	       longer than \c B_MIME_TYPE_LENGTH (including the terminating
@@ -146,6 +160,8 @@
 	\retval B_OK Everything went fine.
 	\retval B_NO_INIT The object was not properly initialized.
 	\retval B_BAD_VALUE \a type is longer than \c B_MIME_TYPE_LENGTH.
+
+	\since BeOS R3
 */
 
 
@@ -153,7 +169,7 @@
 
 
 /*!
-	\name Icon methods
+	\name Icon
 */
 
 
@@ -161,28 +177,30 @@
 
 
 /*!
-	\fn status_t BNodeInfo::GetIcon(BBitmap *icon, icon_size k) const
+	\fn status_t BNodeInfo::GetIcon(BBitmap* icon, icon_size which) const
 	\brief Gets the icon of the node.
 
 	The icon stored in the \c BEOS:L:STD_ICON attribute (large) or
 	\c BEOS:M:STD_ICON attribute (mini) is retrieved.
 
 	\param icon A pointer to a pre-allocated BBitmap object of the correct
-		   dimension to store the requested icon: 16x16 for the mini or
+	       dimension to store the requested icon: 16x16 for the mini or
-		   32x32 for the large icon.
+	       32x32 for the large icon.
-	\param k The size of the icon to be retrieved: \c B_MINI_ICON for a 16x16
+	\param which The size of the icon to be retrieved: \c B_MINI_ICON for a 16x16
 	       icon and \c B_LARGE_ICON for a 32x32 icon.
 
 	\returns A status code.
 	\retval B_OK Everything went fine.
 	\retval B_NO_INIT The object was not properly initialized.
 	\retval B_BAD_VALUE \c NULL \a icon, unsupported icon size \a k or bitmap
-		    dimensions (\a icon) and icon size (\a k) do not match.
+	        dimensions (\a icon) and icon size (\a k) do not match.
+
+	\since BeOS R3
 */
 
 
 /*!
-	\fn status_t BNodeInfo::SetIcon(const BBitmap *icon, icon_size k)
+	\fn status_t BNodeInfo::SetIcon(const BBitmap* icon, icon_size which)
 	\brief Sets the icon of the node. If \a icon is \c NULL, the attribute is
 		   removed instead.
 
@@ -191,15 +209,17 @@
 	attribute is removed instead.
 
 	\param icon A pointer to a BBitmap object containing the icon to be set.
-		   May be \c NULL.
+	       May be \c NULL.
-	\param k The size of the icon to be set: \c B_MINI_ICON for the mini or
+	\param which The size of the icon to be set: \c B_MINI_ICON for the mini or
 	       \c B_LARGE_ICON for the large icon.
 
 	\returns A status code.
 	\retval B_OK Everything went fine.
 	\retval B_NO_INIT The object is not properly initialized.
 	\retval B_BAD_VALUE Unknown icon size \a k or bitmap dimensions (\a icon)
-		    and icon size (\a k) do not match.
+	        and icon size (\a k) do not match.
+
+	\since BeOS R3
 */
 
 
@@ -213,17 +233,19 @@
 	retrieved.
 
 	\param data A pointer in which a pointer to the icon data
-		   will be returned.
+	       will be filled in.
 	\param size A pointer in which the size of the found icon data
-		   will be returned.
+	       will be filled in.
 	\param type A pointer in which the type of the found icon data
-		   will be returned.
+	       will be filled in.
 
 	\returns A status code.
 	\retval B_OK Everything went fine.
 	\retval B_NO_INIT The object was not properly initialized.
 	\retval B_BAD_VALUE \c NULL \a data, \c NULL \a size or \c NULL \a type.
 	\retval B_NO_MEMORY No memory to allocate the \a data buffer.
+
+	\since Haiku R1
 */
 
 
@@ -240,12 +262,14 @@
 	\returns A status code.
 	\retval B_OK Everything went fine.
 	\retval B_NO_INIT The object was not properly initialized.
+
+	\since Haiku R1
 */
 
 
 /*!
-	\fn status_t BNodeInfo::GetTrackerIcon(BBitmap *icon,
+	\fn status_t BNodeInfo::GetTrackerIcon(BBitmap* icon,
-		icon_size iconSize) const
+		icon_size which) const
 	\brief Gets the icon displayed by Tracker for the icon.
 
 	This method tries really hard to find an icon for the node:
@@ -268,7 +292,7 @@
 	The first action that provides an icon is used. In the case that none of
 	them yield an icon this method fails, this is very unlikely though.
 
-	\remarks You can set \a iconSize to get a scaled icon instead of using
+	\remarks You can set \a which to get a scaled icon instead of using
 	         a predefined icon_size constant, pass in an integer casted
 	         to icon_size. For example to get a 64x64 icon pass in:
 \code
@@ -276,44 +300,48 @@
 \endcode
 
 	\param icon A pointer to a pre-allocated BBitmap of the correct dimension
-		   to store the requested icon (16x16 for the mini and 32x32 for the
+	       to store the requested icon (16x16 for the mini and 32x32 for the
-		   large icon).
+	       large icon).
-	\param iconSize The size of the icon to be retrieved: \c B_MINI_ICON
+	\param which The size of the icon to be retrieved: \c B_MINI_ICON
-		   for a 16x16 icon or \c B_LARGE_ICON for a 32x32 icon.
+	       for a 16x16 icon or \c B_LARGE_ICON for a 32x32 icon.
 
 	\returns A status code.
 	\retval B_OK Everything went fine.
 	\retval B_NO_INIT The object was not properly initialized.
-	\retval B_BAD_VALUE \c NULL \a icon, unsupported icon size \a iconSize
+	\retval B_BAD_VALUE \c NULL \a icon, unsupported icon size \a which
-	        or bitmap dimensions (\a icon) and icon size (\a iconSize) do
+	        or bitmap dimensions (\a icon) and icon size (\a which) do
 	        not match.
+
+	\since BeOS R3
 */
 
 
 /*!
-	\fn status_t BNodeInfo::GetTrackerIcon(const entry_ref *ref,
+	\fn status_t BNodeInfo::GetTrackerIcon(const entry_ref* ref,
-		BBitmap *icon, icon_size iconSize)
+		BBitmap* icon, icon_size which)
 	\brief Gets the icon displayed by Tracker for the node referred to by
 	       \a ref.
 
 	This methods works similarly to the non-static version but \a ref
 	identifies the node. \a icon must be pre-allocated to the size requested
-	using \a iconSize before being passed to this method.
+	using \a which before being passed to this method.
 
 	\param ref An entry_ref referring to the node for which the icon is
 	       retrieved.
 	\param icon A pointer to a pre-allocated BBitmap object of the correct
 	       dimension to store the requested icon (16x16 for the mini and 32x32
 	       for the large icon).
-	\param iconSize The size of the icon to be retrieved: \c B_MINI_ICON
+	\param which The size of the icon to be retrieved: \c B_MINI_ICON
 	       for a 16x16 icon or \c B_LARGE_ICON for a 32x32 icon.
 
 	\returns A status code.
 	\retval B_OK: Everything went fine.
 	\retval B_NO_INIT: The object is not properly initialized.
 	\retval B_BAD_VALUE: \c NULL ref or \a icon, unsupported icon size
-	        \a iconSize or bitmap dimensions (\a icon) and icon size
+	        \a which or bitmap dimensions (\a icon) and icon size
-	        (\a iconSize) do not match.
+	        (\a which) do not match.
+
+	\since BeOS R3
 */
 
 
@@ -321,7 +349,7 @@
 
 
 /*!
-	\name Preferred application methods
+	\name Preferred Application
 */
 
 
@@ -329,7 +357,7 @@
 
 
 /*!
-	\fn status_t BNodeInfo::GetPreferredApp(char *signature,
+	\fn status_t BNodeInfo::GetPreferredApp(char* signature,
 		app_verb verb) const
 	\brief Gets the preferred application of the node.
 
@@ -352,7 +380,7 @@
 
 
 /*!
-	\fn status_t BNodeInfo::SetPreferredApp(const char *signature,
+	\fn status_t BNodeInfo::SetPreferredApp(const char* signature,
 		app_verb verb)
 	\brief Sets the preferred application of the node. If \a signature is
 	       \c NULL, the \c BEOS:PREF_APP attribute is removed instead.
@@ -379,7 +407,7 @@
 
 
 /*!
-	\name Application hint methods
+	\name Application Hint
 */
 
 
@@ -387,7 +415,7 @@
 
 
 /*!
-	\fn status_t BNodeInfo::GetAppHint(entry_ref *ref) const
+	\fn status_t BNodeInfo::GetAppHint(entry_ref* ref) const
 	\brief Fills out \a ref with a pointer to a hint about the application
 	       that will open this node.
 
@@ -409,7 +437,7 @@
 
 
 /*!
-	\fn status_t BNodeInfo::SetAppHint(const entry_ref *ref)
+	\fn status_t BNodeInfo::SetAppHint(const entry_ref* ref)
 	\brief Sets the application that will open the file type of the node. If
 	       \a ref is \c NULL, the \c BEOS:PPATH attribute is removed instead.
 

docs/user/storage/NodeMonitor.dox

@@ -1,5 +1,5 @@
 /*
- * Copyright 2003-2013 Haiku Inc. All rights reserved.
+ * Copyright 2003-2014 Haiku, Inc. All rights reserved.
  * Distributed under the terms of the MIT License.
  *
  * Authors:
@@ -9,8 +9,8 @@
  *		Clemens Zeidler, [email protected]
  *
  * Corresponds to:
- *		headers/os/storage/NodeMonitor.h	hrev45253
+ *		headers/os/storage/NodeMonitor.h	hrev47402
- *		src/kits/storage/NodeMonitor.cpp	hrev45253
+ *		src/kits/storage/NodeMonitor.cpp	hrev47402
  */
 
 
@@ -21,7 +21,7 @@
 	\brief Provides functions and constants for monitoring changes to a node.
 
 	The are three main node monitoring functions are watch_volume(),
-	watch_node() and stop_watching().
+	watch_node(), and stop_watching().
 	- watch_volume() starts watching a volume and sends a message
 	  when a requested event occurs.
 	- watch_node() starts or stops watching a node, or watches for volumes
@@ -31,219 +31,279 @@
 */
 
 
+//// Flags for the watch_node() call.
+
+
 /*!
 	\var B_STOP_WATCHING
+	\brief Unsubscribe from watching a node.
 
-	Flag for watch_node(). Unsubscribe from watching a node.
+	Flag for watch_node().
 
 	\attention \c B_STOP_WATCHING does not apply to volume watching, you must
 	           call stop_watching() instead.
+
+	\since BeOS R3
 */
 
 
 /*!
 	\var B_WATCH_NAME
+	\brief Subscribe to watching for change to the name of a node.
 
-	Flag for watch_volume() and watch_node(). Subscribe to watching for
+	Flag for watch_volume() and watch_node().
-	change to the name of a node.
+
+	\since BeOS R3
 */
 
 
 /*!
 	\var B_WATCH_STAT
+	\brief Subscribe to watching for changes to the stat information of a node.
 
-	Flag for watch_volume() and watch_node(). Subscribe to watching for
+	Flag for watch_volume() and watch_node().
-	changes to the stat information of a node.
+
+	\since BeOS R3
 */
 
 
 /*!
 	\var B_WATCH_ATTR
+	\brief Subscribe to watching for changes to the attributes of a node.
 
-	Flag for watch_volume() and watch_node(). Subscribe to watching for
+	Flag for watch_volume() and watch_node().
-	changes to the attributes of a node.
+
+	\since BeOS R3
 */
 
 
 /*!
 	\var B_WATCH_DIRECTORY
+	\brief Subscribe to watching for changes to the contents of a directory.
 
-	Flag for watch_node(). Subscribe to watching for changes to the contents
+	Flag for watch_node().
-	of a directory.
+
+	\since BeOS R3
 */
 
 
 /*!
 	\var B_WATCH_ALL
+	\brief Flag for watch_node().
 
-	Flag for watch_node(). Subscribe to watching for changes to all
+	Subscribe to watching for changes to all information of a node except
-	information of a node except \c B_WATCH_MOUNT.
+	\c B_WATCH_MOUNT.
+
+	\since BeOS R3
 */
 
 
 /*!
 	\var B_WATCH_MOUNT
+	\brief  Subscribe to watching for when a volume is mounted or unmounted.
 
-	Flag for watch_node(). Subscribe to watching for when a volume is mounted
+	You may prefer to use BVolumeRoster for volume watching instead.
-	or unmounted. You may prefer to use BVolumeRoster for volume watching
+
-	instead.
+	Flag for watch_node().
+
+	\since BeOS R3
 */
 
 
 /*!
 	\var B_WATCH_INTERIM_STAT
+	\brief To avoid a flood of messages for small and frequent write operations
+	       on an open file the file system can limit the number of
+	       notifications and mark them with the \c B_WATCH_INTERIM_STAT flag.
 
-	\internal Implementation detail. Not in Be Book.
+	\internal Implementation detail, not in Be Book.
 
-	To avoid a flood of messages for small and frequent write operations on an
+	\since Haiku R1
-	open file the file system can limit the number of notifications and mark
-	them with the \c B_WATCH_INTERIM_STAT flag.
 */
 
 
+//// The "opcode" field of the B_NODE_MONITOR notification message you get.
+
+
 /*!
-	\def B_ENTRY_CREATED
+	\var B_ENTRY_CREATED
 
 	\c B_NODE_MONITOR notification message "opcode" is set when entry is
 	created.
+
+	\since BeOS R3
 */
 
 
 /*!
-	\def B_ENTRY_REMOVED
+	\var B_ENTRY_REMOVED
 
 	\c B_NODE_MONITOR notification message "opcode" is set when entry is
 	removed.
+
+	\since BeOS R3
 */
 
 
 /*!
-	\def B_ENTRY_MOVED
+	\var B_ENTRY_MOVED
 
 	\c B_NODE_MONITOR notification message "opcode" is set when entry is
 	moved.
+
+	\since BeOS R3
 */
 
 
 /*!
-	\def B_STAT_CHANGED
+	\var B_STAT_CHANGED
 
 	\c B_NODE_MONITOR notification message "opcode" set when stat info
 	changes. More information can be found in the "fields" field.
+
+	\since BeOS R3
 */
 
 
 /*!
-	\def B_ATTR_CHANGED
+	\var B_ATTR_CHANGED
 
 	\c B_NODE_MONITOR notification message "opcode" set when attribute
 	changes. More information can be found in the "cause" field.
+
+	\since BeOS R3
 */
 
 
 /*!
-	\def B_DEVICE_MOUNTED
+	\var B_DEVICE_MOUNTED
 
 	\c B_NODE_MONITOR notification message "opcode" set when device is
 	mounted.
+
+	\since BeOS R3
 */
 
 
 /*!
-	\def B_DEVICE_UNMOUNTED
+	\var B_DEVICE_UNMOUNTED
 
 	\c B_NODE_MONITOR notification message "opcode" set when device is
 	unmounted.
+
+	\since BeOS R3
 */
 
 
 /*!
-	\def B_ATTR_CREATED
+	\var B_ATTR_CREATED
 
 	\c B_ATTR_CHANGED notification message "cause" set when attribute is
-	created. (Haiku only)
+	created.
+
+	\since Haiku R1
 */
 
 
 /*!
-	\def B_ATTR_REMOVED
+	\var B_ATTR_REMOVED
 
 	\c B_ATTR_CHANGED notification message "cause" set when attribute is
-	removed. (Haiku only)
+	removed.
+
+	\since Haiku R1
 */
 
 
 /*!
 	\var B_STAT_MODE
+	\brief Set when stat mode changes.
 
-	\c B_STAT_CHANGED notification messages "fields" flag set when stat mode
+	\c B_STAT_CHANGED notification messages "fields" flag.
-	changes.
+
+	\since Haiku R1
 */
 
 
 /*!
 	\var B_STAT_UID
+	\brief Set when UID changes.
 
-	\c B_STAT_CHANGED notification messages "fields" flag set when UID
+	\c B_STAT_CHANGED notification messages "fields" flag.
-	changes.
+
+	\since Haiku R1
 */
 
 
 /*!
 	\var B_STAT_GID
+	\brief Set when GID changes.
 
-	\c B_STAT_CHANGED notification messages "fields" flag set when GID
+	\c B_STAT_CHANGED notification messages "fields" flag.
-	changes.
+
+	\since Haiku R1
 */
 
 
 /*!
 	\var B_STAT_SIZE
+	\brief Set when stat size changes.
 
-	\c B_STAT_CHANGED notification messages "fields" flag set when stat size
+	\c B_STAT_CHANGED notification messages "fields" flag.
-	changes.
+
+	\since Haiku R1
 */
 
 
 /*!
 	\var B_STAT_ACCESS_TIME
+	\brief Set when access time changes.
 
-	\c B_STAT_CHANGED notification messages "fields" flag set when access time
+	\c B_STAT_CHANGED notification messages "fields" flag.
-	changes.
+
+	\since Haiku R1
 */
 
 
 /*!
 	\var B_STAT_MODIFICATION_TIME
+	\brief Set when modification time changes.
 
-	\c B_STAT_CHANGED notification messages "fields" flag set when
+	\c B_STAT_CHANGED notification messages "fields" flag.
-	modification time changes.
+
+	\since Haiku R1
 */
 
 
 /*!
 	\var B_STAT_CREATION_TIME
+	\brief Set when creation time changes.
 
-	\c B_STAT_CHANGED notification messages "fields" flag set when creation
+	\c B_STAT_CHANGED notification messages "fields" flag.
-	time changes.
+
+	\since Haiku R1
 */
 
 
 /*!
 	\var B_STAT_CHANGE_TIME
+	\brief Set when access, modification or creation time changes.
 
-	\c B_STAT_CHANGED notification messages "fields" flag set when access,
+	\c B_STAT_CHANGED notification messages "fields" flag.
-	modification or creation time changes.
+
+	\since Haiku R1
 */
 
 
 /*!
 	\var B_STAT_INTERIM_UPDATE
+	\brief Set when file is written to.
 
-	\internal Implementation detail. Not in Be Book.
+	\internal Implementation detail, not in Be Book.
 
-	\c B_STAT_CHANGED notification messages "fields" flag set when file is
+	\c B_STAT_CHANGED notification messages "fields" flag.
-	written to.
+
+	\since Haiku R1
 */
 
 
@@ -271,12 +331,14 @@
 	\retval B_OK Everything went fine.
 	\retval B_BAD_VALUE \a flags did not include one of \c B_WATCH_NAME,
 	        \c B_WATCH_STAT, or \c B_WATCH_ATTR.
+
+	\since Haiku R1
 */
 
 
 /*!
 	\fn status_t watch_volume(dev_t volume, uint32 flags,
-		const BHandler *handler, const BLooper *looper)
+		const BHandler* handler, const BLooper* looper)
 	\brief Subscribes \a handler or \a looper to watch node changes on
 	       \a volume.
 
@@ -303,11 +365,13 @@
 	\retval B_OK Everything went fine.
 	\retval B_BAD_VALUE \a flags did not include one of \c B_WATCH_NAME,
 	        \c B_WATCH_STAT, or \c B_WATCH_ATTR.
+
+	\since Haiku R1
 */
 
 
 /*!
-	\fn status_t watch_node(const node_ref *node, uint32 flags,
+	\fn status_t watch_node(const node_ref* node, uint32 flags,
 		BMessenger target)
 	\brief Subscribes or unsubscribes \a target to node and/or mount watching.
 
@@ -341,12 +405,14 @@
 	\param target BMessenger object referring to the \a target.
 
 	\return \c B_OK if everything went fine, an error code otherwise.
+
+	\since BeOS R3
 */
 
 
 /*!
-	\fn status_t watch_node(const node_ref *node, uint32 flags,
+	\fn status_t watch_node(const node_ref* node, uint32 flags,
-		const BHandler *handler, const BLooper *looper)
+		const BHandler* handler, const BLooper* looper)
 	\brief Subscribes or unsubscribes \a handler or \a looper to node and/or
 	       mount watching.
 
@@ -383,6 +449,8 @@
 	       \c NULL. Then the handler's looper is the target looper.
 
 	\return \c B_OK if everything went fine, an error code otherwise.
+
+	\since BeOS R3
 */
 
 
@@ -403,11 +471,13 @@
 	\retval B_OK Stopped sending notification messages to the \a target.
 	\retval B_BAD_VALUE \a target was invalid.
 	\retval B_ENTRY_NOT_FOUND Node not found.
+
+	\since BeOS R3
 */
 
 
 /*!
-	\fn status_t stop_watching(const BHandler *handler, const BLooper *looper)
+	\fn status_t stop_watching(const BHandler* handler, const BLooper* looper)
 	\brief Unsubscribes \a handler or \a looper target from node and mount
 	       monitoring.
 
@@ -427,4 +497,6 @@
 	\retval B_OK Stopped sending notification messages to the target.
 	\retval B_BAD_VALUE Target from \a handler or \a looper was invalid.
 	\retval B_ENTRY_NOT_FOUND Node not found.
+
+	\since BeOS R3
 */

docs/user/storage/Path.dox

@@ -9,8 +9,8 @@
  *		Ingo Weinhold, [email protected]
  *
  * Corresponds to:
- *		headers/os/storage/Path.h	hrev45260
+ *		headers/os/storage/Path.h	hrev47402
- *		src/kits/storage/Path.cpp	hrev45260
+ *		src/kits/storage/Path.cpp	hrev47402
  */
 
 
@@ -27,6 +27,8 @@
 	\ingroup storage
 	\ingroup libbe
 	\brief A class representing a file system path.
+
+	\since BeOS R3
 */
 
 
@@ -43,6 +45,8 @@
 	\brief Creates a copy of the given BPath object.
 
 	\param path the object to be copied.
+
+	\since BeOS R3
 */
 
 
@@ -52,6 +56,8 @@
 	       specified by the passed in entry_ref struct.
 
 	\param ref the entry_ref to initialize from.
+
+	\since BeOS R5
 */
 
 
@@ -61,6 +67,8 @@
 	       specified by the passed in BEntry object.
 
 	\param entry the BEntry object to initialize from.
+
+	\since BeOS R4
 */
 
 
@@ -81,6 +89,8 @@
 	       - The presence of "." or ".." ("/boot/ltj/../ltj/./gwar")
 	       - Redundant slashes ("/boot//ltj")
 	       - A trailing slash ("/boot/ltj/")
+
+	\since BeOS R3
 */
 
 
@@ -100,17 +110,21 @@
 	       - The presence of "." or ".." ("/boot/ltj/../ltj/./gwar")
 	       - Redundant slashes ("/boot//ltj")
 	       - A trailing slash ("/boot/ltj/")
+
+	\since BeOS R3
 */
 
 
 /*!
 	\fn BPath::~BPath()
 	\brief Destroys the BPath object and frees any associated resources.
+
+	\since BeOS R3
 */
 
 
 /*!
-	\name Constructor helper methods
+	\name Constructor Helpers
 */
 
 
@@ -123,6 +137,8 @@
 
 	\return \c B_OK, if the BPath object was properly initialized, an error
 	        code otherwise.
+
+	\since BeOS R3
 */
 
 
@@ -136,6 +152,8 @@
 	\retval B_OK Initialization was successful.
 	\retval B_BAD_VALUE \a ref was \c NULL.
 	\retval B_NAME_TOO_LONG The pathname was longer than \c B_PATH_NAME_LENGTH.
+
+	\since BeOS R5
 */
 
 
@@ -149,6 +167,8 @@
 	\retval B_OK Initialization was successful.
 	\retval B_BAD_VALUE \a ref was \c NULL.
 	\retval B_NAME_TOO_LONG The pathname was longer than \c B_PATH_NAME_LENGTH.
+
+	\since BeOS R4
 */
 
 
@@ -174,6 +194,8 @@
 	\retval B_OK Initialization was successful.
 	\retval B_BAD_VALUE \a ref was \c NULL.
 	\retval B_NAME_TOO_LONG The pathname was longer than \c B_PATH_NAME_LENGTH.
+
+	\since BeOS R3
 */
 
 
@@ -197,6 +219,8 @@
 	\retval B_OK Initialization was successful.
 	\retval B_BAD_VALUE \a ref was \c NULL.
 	\retval B_NAME_TOO_LONG The pathname was longer than \c B_PATH_NAME_LENGTH.
+
+	\since BeOS R3
 */
 
 
@@ -205,6 +229,8 @@
 	\brief Returns the object to an uninitialized state.
 
 	Frees any resources it allocated and marks the object as uninitialized.
+
+	\since BeOS R3
 */
 
 
@@ -212,7 +238,7 @@
 
 
 /*!
-	\name Path manipulation methods
+	\name Path Manipulation
 */
 
 
@@ -239,6 +265,8 @@
 	\retval B_OK Initialization was successful.
 	\retval B_BAD_VALUE \a ref was \c NULL.
 	\retval B_NAME_TOO_LONG The pathname was longer than \c B_PATH_NAME_LENGTH.
+
+	\since BeOS R3
 */
 
 
@@ -246,7 +274,7 @@
 
 
 /*!
-	\name Path information methods
+	\name Path Information
 */
 
 
@@ -259,6 +287,8 @@
 
 	\returns The path name of the object, or \c NULL if it is not properly
 	         initialized.
+
+	\since BeOS R3
 */
 
 
@@ -271,6 +301,8 @@
 
 	\returns The leaf portion of the path or \c NULL if it is not properly
 	         initialized.
+
+	\since BeOS R3
 */
 
 
@@ -305,7 +337,7 @@
 
 
 /*!
-	\name Operator overload methods
+	\name Operators
 */
 
 
@@ -322,6 +354,8 @@
 	\param item the BPath object to compare.
 
 	\return \c true, if the paths are equal, \c false otherwise.
+
+	\since BeOS R3
 */
 
 
@@ -334,6 +368,8 @@
 	\param path The path to compare.
 
 	\return \c true, if the path names are equal, \c false otherwise.
+
+	\since BeOS R3
 */
 
 
@@ -347,6 +383,8 @@
 	\param item the BPath object to compare.
 
 	\return \c true, if the path names are \b not equal, \c false otherwise.
+
+	\since BeOS R3
 */
 
 
@@ -359,6 +397,8 @@
 	\param path The path to compare.
 
 	\return \c true, if the path names are \b not equal, \c false otherwise.
+
+	\since BeOS R3
 */
 
 
@@ -369,6 +409,8 @@
 	\param item The BPath object to copy
 
 	\return A pointer to the newly initialized BPath object.
+
+	\since BeOS R3
 */
 
 
@@ -381,6 +423,8 @@
 	\param path the path to be assign to this object.
 
 	\return A pointer to the newly initialized BPath object.
+
+	\since BeOS R3
 */
 
 
@@ -388,7 +432,7 @@
 
 
 /*!
-	\name BFlattenable method implementations
+	\name BFlattenable Method Implementations
 */
 
 
@@ -400,6 +444,8 @@
 	\brief Implements BFlattenable::IsFixedSize(). Always returns \c false.
 
 	\return \c false
+
+	\since BeOS R3
 */
 
 
@@ -408,6 +454,8 @@
 	\brief Implements BFlattenable::TypeCode(). Always returns \c B_REF_TYPE.
 
 	\return \c B_REF_TYPE
+
+	\since BeOS R3
 */
 
 
@@ -418,6 +466,8 @@
 
 	\return The size of the flattened entry_ref struct that represents the
 	        path in bytes.
+
+	\since BeOS R3
 */
 
 
@@ -432,6 +482,8 @@
 	\returns A status code.
 	\retval B_OK Everything went fine.
 	\retval B_BAD_VALUE \a buffer was \c NULL or of insufficient size.
+
+	\since BeOS R3
 */
 
 
@@ -443,6 +495,8 @@
 	\param code The type code to test.
 
 	\return \c true if code is \c B_REF_TYPE, \c false otherwise.
+
+	\since BeOS R3
 */
 
 
@@ -461,42 +515,9 @@
 	\returns A status code.
 	\retval B_OK Everything went fine.
 	\retval B_BAD_VALUE \a buffer was \c NULL or didn't contain an entry_ref.
+
+	\since BeOS R3
 */
 
 
 //! @}
-
-
-/// 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 the path of the object is set to
-	\c NULL as well. The 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.
-*/

docs/user/storage/PathFinder.dox

@@ -1,13 +1,14 @@
 /*
- * Copyright 2013, Haiku, Inc. All rights reserved.
+ * Copyright 2013-2014 Haiku, Inc. All rights reserved.
  * Distributed under the terms of the MIT License.
  *
  * Documentation by:
+ *		John Scipione, [email protected]
  *		Ingo Weinhold, [email protected]
  *
  * Corresponds to:
- *		headers/os/storage/PathFinder.h	 hrev46390
+ *		headers/os/storage/PathFinder.h	 hrev47402
- *		src/kits/storage/PathFinder.cpp	 hrev46390
+ *		src/kits/storage/PathFinder.cpp	 hrev47402
  */
 
 
@@ -29,6 +30,8 @@
 	FindPath() for getting a single path in an installation location specified
 	via a constructor or a SetTo() invocation, and the static FindPaths() for
 	getting a list of paths for all installation locations.
+
+	\since Haiku R1
 */
 
 
@@ -36,7 +39,7 @@
 	\fn BPathFinder::BPathFinder(const void* codePointer,
 		const char* dependency)
 	\brief Creates an object referring to an installation location based on a
-		loaded image file.
+	       loaded image file.
 
 	When initialized with this constructor a FindPath() method called afterward
 	determines the path of the image (i.e. executable, library, or add-on) file
@@ -53,23 +56,25 @@
 	arguments, subsequent calls to FindPath() will return an error.
 
 	\param codePointer A pointer to code or static data belonging to the image
-		based on which FindPath() shall compute the path. The special value
+	       based on which FindPath() shall compute the path. The special value
-		\c B_APP_IMAGE_SYMBOL (the default) can be used to refer to the program
+	       \c B_APP_IMAGE_SYMBOL (the default) can be used to refer to the
-		image, and \c B_CURRENT_IMAGE_SYMBOL for the caller's image.
+	       program image, and \c B_CURRENT_IMAGE_SYMBOL for the caller's image.
 	\param dependency The name of the package's "requires" entry to be used for
-		resolving the installation location. Can be \c NULL (the default).
+	       resolving the installation location. Can be \c NULL (the default).
+
+	\since Haiku R1
 */
 
 
 /*!
 	\fn BPathFinder::BPathFinder(const char* path, const char* dependency)
 	\brief Creates an object referring to an installation location based on a
-		given path.
+	       given \a path.
 
 	When initialized with this constructor a FindPath() method called afterward
 	evaluates the path constant passed to it based on \a path. In most cases
 	that means first determining the path of the installation location from the
-	given path.
+	given \a path.
 
 	If \a dependency is specified, instead of determining the installation
 	location path from the given path, the installation location path of the
@@ -80,48 +85,55 @@
 	arguments, subsequent calls to FindPath() will return an error.
 
 	\param path A path based on which FindPath() shall compute the path.
-	\param dependency The name of the package's "requires" entry to be used for
+	\param dependency The name of the package's "requires" entry to be used
-		resolving the installation location. Can be \c NULL.
+	       for resolving the installation location. Can be \c NULL.
+
+	\since Haiku R1
 */
 
 
 /*!
 	\fn BPathFinder::BPathFinder(const entry_ref& ref, const char* dependency)
 	\brief Creates an object referring to an installation location based on a
-		given entry_ref.
+	       given entry_ref.
 
 	The constructor converts the given entry_ref \a ref to a path and then
 	initializes the object like
 	BPathFinder::BPathFinder(const char*, const char*).
 
 	\param ref A reference to be resolved to a path based on which FindPath()
-		shall compute the path.
+	       shall compute the path.
-	\param dependency The name of the package's "requires" entry to be used for
+	\param dependency The name of the package's "requires" entry to be used
-		resolving the installation location. Can be \c NULL.
+	       for resolving the installation location. Can be \c NULL.
 
 	\see BPathFinder::BPathFinder(const char*, const char*)
+
+	\since Haiku R1
 */
 
 
 /*!
 	\fn BPathFinder::BPathFinder(const BResolvableExpression& expression,
 		const char* dependency)
-	\brief Creates an object referring to an installation location based on the
+	\brief Creates an object referring to an installation location based on
-		path of a package satisfying the given resolvable expression.
+	       the path of a package satisfying the given resolvable expression.
 
 	The constructor finds the latest package that satisfies the resolvable
 	expression \a expression and then uses its path to initialize the object
 	like BPathFinder::BPathFinder(const char*, const char*).
 
-	\note When using this constructor linking against libpackage.so is required.
+	\note When using this constructor linking against libpackage.so is
+	      required.
 
-	\param expression A resolvable expression to be resolved to the path of the
+	\param expression A resolvable expression to be resolved to the path of
-		latest package satisfying it, based on which FindPath() shall compute
+	       the latest package satisfying it, based on which FindPath() shall
-		the path.
+	       compute the path.
-	\param dependency The name of the package's "requires" entry to be used for
+	\param dependency The name of the package's "requires" entry to be used
-		resolving the installation location. Can be \c NULL.
+	       for resolving the installation location. Can be \c NULL.
 
 	\see BPathFinder::BPathFinder(const char*, const char*)
+
+	\since Haiku R1
 */
 
 
@@ -129,14 +141,15 @@
 	\fn status_t BPathFinder::SetTo(const void* codePointer,
 		const char* dependency)
 	\brief Reinitializes the object to refer to an installation location based
-		on a loaded image file.
+	       on a loaded image file.
 
 	When reinitialized with this method a FindPath() method called afterward
-	determines the path of the image (i.e. executable, library, or add-on) file
+	determines the path of the image (i.e. executable, library, or add-on)
-	associated with \a codePointer, a pointer to a location in the code or
+	file associated with \a codePointer, a pointer to a location in the code
-	static data of an image loaded in the caller's team. Based on that path the
+	or static data of an image loaded in the caller's team. Based on that path
-	path constant passed to FindPath() will be evaluated. In most cases that
+	the path constant passed to FindPath() will be evaluated. In most cases
-	means first determining the path of the installation location from the path.
+	that means first determining the path of the installation location from
+	the path.
 
 	If \a dependency is specified, instead of determining the installation
 	location path from the image path, the installation location path of the
@@ -147,25 +160,28 @@
 	error.
 
 	\param codePointer A pointer to code or static data belonging to the image
-		based on which FindPath() shall compute the path. The special value
+	       based on which FindPath() shall compute the path. The special value
-		\c B_APP_IMAGE_SYMBOL (the default) can be used to refer to the program
+	       \c B_APP_IMAGE_SYMBOL (the default) can be used to refer to the
-		image, and \c B_CURRENT_IMAGE_SYMBOL for the caller's image.
+	       program image, and \c B_CURRENT_IMAGE_SYMBOL for the caller's image.
 	\param dependency The name of the package's "requires" entry to be used for
-		resolving the installation location. Can be \c NULL (the default).
+	       resolving the installation location. Can be \c NULL (the default).
+
 	\return A status code.
 	\retval B_OK Everything went fine.
+
+	\since Haiku R1
 */
 
 
 /*!
 	\fn status_t BPathFinder::SetTo(const char* path, const char* dependency)
 	\brief Reinitializes the object to refer to an installation location based
-		on a given path.
+	       on a given \a path.
 
 	When reinitialized with this method a FindPath() method called afterward
 	evaluates the path constant passed to it based on \a path. In most cases
-	that means first determining the path of the installation location from the
+	that means first determining the path of the installation location from
-	given path.
+	the given \a path.
 
 	If \a dependency is specified, instead of determining the installation
 	location path from the given path, the installation location path of the
@@ -178,9 +194,11 @@
 
 	\param path A path based on which FindPath() shall compute the path.
 	\param dependency The name of the package's "requires" entry to be used for
-		resolving the installation location. Can be \c NULL.
+	       resolving the installation location. Can be \c NULL.
-	\return A status code.
+
-	\retval B_OK Everything went fine.
+	\return \c B_OK Everything if went fine or an error code otherwise.
+
+	\since Haiku R1
 */
 
 
@@ -188,17 +206,21 @@
 	\fn status_t BPathFinder::SetTo(const entry_ref& ref,
 		const char* dependency)
 	\brief Reinitializes the object to refer to an installation location based
-		on a given entry_ref.
+	       on a given entry_ref.
 
 	This method converts the given entry_ref \a ref to a path and then calls
 	calls BPathFinder::SetTo(const char*, const char*).
 
 	\param ref A reference to be resolved to a path based on which FindPath()
-		shall compute the path.
+	       shall compute the path.
-	\param dependency The name of the package's "requires" entry to be used for
+	\param dependency The name of the package's "requires" entry to be used
-		resolving the installation location. Can be \c NULL.
+	       for resolving the installation location. Can be \c NULL.
 
 	\see status_t BPathFinder::SetTo(const char*, const char*)
+
+	\return \c B_OK Everything if went fine or an error code otherwise.
+
+	\since Haiku R1
 */
 
 
@@ -221,6 +243,10 @@
 		resolving the installation location. Can be \c NULL.
 
 	\see status_t BPathFinder::SetTo(const char*, const char*)
+
+	\return \c B_OK Everything if went fine or an error code otherwise.
+
+	\since Haiku R1
 */
 
 
@@ -258,27 +284,30 @@
 	resolved to is returned.
 
 	\param architecture The name of the architecture to be used for resolving
-		architecture dependent paths. Can be \c NULL, in which case the
+	       \a architecture dependent paths. Can be \c NULL, in which case the
-		architecture associated with the initial path is used.
+	       \a architecture associated with the initial path is used.
 	\param baseDirectory Constant indicating which path to retrieve.
 	\param subPath Relative subpath that shall be appended. Can be \c NULL.
 	\param flags Bitwise OR of any of the following flags:
-		- \c B_FIND_PATH_CREATE_DIRECTORY: If the resulting path doesn't exist,
+	       - \c B_FIND_PATH_CREATE_DIRECTORY: If the resulting path doesn't
-			create it as a directory (including all missing ancestors).
+	         exist, create it as a directory (including all missing ancestors).
-		- \c B_FIND_PATH_CREATE_PARENT_DIRECTORY: If the resulting path's parent
+	       - \c B_FIND_PATH_CREATE_PARENT_DIRECTORY: If the resulting path's
-			doesn't exist, create the parent directory (including all missing
+	         parent doesn't exist, create the parent directory (including all
-			ancestors).
+	         missing ancestors).
-		- \c B_FIND_PATH_EXISTING_ONLY: If the resulting path doesn't exist,
+	       - \c B_FIND_PATH_EXISTING_ONLY: If the resulting path doesn't exist,
-			fail with \c B_ENTRY_NOT_FOUND.
+	         fail with \c B_ENTRY_NOT_FOUND.
 	\param _path The variable to be set to the resulting path on success.
+
 	\return A status code.
 	\retval B_OK Everything went fine.
 	\retval B_ENTRY_NOT_FOUND A file system entry required for retrieving the
-		path doesn't exist. E.g. \c B_FIND_PATH_PACKAGE_PATH was specified
+	        path didn't exist, e.g. \c B_FIND_PATH_PACKAGE_PATH was specified
-		and the image file doesn't belong to a package, or \c dependency was
+	        and the image file didn't belong to a package, or \c dependency
-		specified, but isn't a "requires" entry of the package, or
+	        was specified, but wasn't a "requires" entry of the package, or
-		\c B_FIND_PATH_EXISTING_ONLY was specified and the resulting path
+	        \c B_FIND_PATH_EXISTING_ONLY was specified and the resulting path
-		doesn't exist.
+	        didn't exist.
+
+	\since Haiku R1
 */
 
 
@@ -294,22 +323,25 @@
 	\param baseDirectory Constant indicating which path to retrieve.
 	\param subPath Relative subpath that shall be appended. Can be \c NULL.
 	\param flags Bitwise OR of any of the following flags:
-		- \c B_FIND_PATH_CREATE_DIRECTORY: If the resulting path doesn't exist,
+	       - \c B_FIND_PATH_CREATE_DIRECTORY: If the resulting path doesn't
-			create it as a directory (including all missing ancestors).
+	         exist, create it as a directory (including all missing ancestors).
-		- \c B_FIND_PATH_CREATE_PARENT_DIRECTORY: If the resulting path's parent
+	       - \c B_FIND_PATH_CREATE_PARENT_DIRECTORY: If the resulting path's
-			doesn't exist, create the parent directory (including all missing
+	         parent doesn't exist, create the parent directory (including all
-			ancestors).
+	         missing ancestors).
-		- \c B_FIND_PATH_EXISTING_ONLY: If the resulting path doesn't exist,
+	       - \c B_FIND_PATH_EXISTING_ONLY: If the resulting path doesn't exist,
-			fail with \c B_ENTRY_NOT_FOUND.
+	         fail with \c B_ENTRY_NOT_FOUND.
 	\param _path The variable to be set to the resulting path on success.
+
 	\return A status code.
 	\retval B_OK Everything went fine.
 	\retval B_ENTRY_NOT_FOUND A file system entry required for retrieving the
-		path doesn't exist. E.g. \c B_FIND_PATH_PACKAGE_PATH was specified
+	        path didn't exist, e.g. \c B_FIND_PATH_PACKAGE_PATH was specified
-		and the image file doesn't belong to a package, or \c dependency was
+	        and the image file didn't belong to a package, or \c dependency
-		specified, but isn't a "requires" entry of the package, or
+	        was specified, but wasn't a "requires" entry of the package, or
-		\c B_FIND_PATH_EXISTING_ONLY was specified and the resulting path
+	        \c B_FIND_PATH_EXISTING_ONLY was specified and the resulting path
-		doesn't exist.
+	        didn't exist.
+
+	\since Haiku R1
 */
 
 
@@ -325,12 +357,13 @@
 	\param baseDirectory Constant indicating which path to retrieve.
 	\param subPath Relative subpath that shall be appended. Can be \c NULL.
 	\param _path The variable to be set to the resulting path on success.
+
 	\return A status code.
 	\retval B_OK Everything went fine.
 	\retval B_ENTRY_NOT_FOUND A file system entry required for retrieving the
-		path doesn't exist. E.g. \c B_FIND_PATH_PACKAGE_PATH was specified
+		path didn't exist, e.g. \c B_FIND_PATH_PACKAGE_PATH was specified
-		and the image file doesn't belong to a package, or \c dependency was
+		and the image file didn't belong to a package, or \c dependency was
-		specified, but isn't a "requires" entry of the package.
+		specified, but wasn't a "requires" entry of the package.
 */
 
 
@@ -348,9 +381,11 @@
 	\return A status code.
 	\retval B_OK Everything went fine.
 	\retval B_ENTRY_NOT_FOUND A file system entry required for retrieving the
-		path doesn't exist. E.g. \c B_FIND_PATH_PACKAGE_PATH was specified
+	        path didn't exist, e.g. \c B_FIND_PATH_PACKAGE_PATH was specified
-		and the image file doesn't belong to a package, or \c dependency was
+	        and the image file didn't belong to a package, or \c dependency
-		specified, but isn't a "requires" entry of the package.
+	        was specified, but wasn't a "requires" entry of the package.
+
+	\since Haiku R1
 */
 
 
@@ -373,26 +408,29 @@
 	valid arguments for this function.
 
 	\param architecture The name of the architecture to be used for resolving
-		architecture dependent paths. Can be \c NULL, in which case the caller's
+	       \a architecture dependent paths. Can be \c NULL, in which case the
-		architecture is used.
+	       caller's \a architecture is used.
 	\param baseDirectory Constant indicating which paths to retrieve.
 	\param subPath Relative subpath that shall be appended. Can be \c NULL.
 	\param flags Bitwise OR of any of the following flags:
-		- \c B_FIND_PATH_CREATE_DIRECTORY: If a resulting path doesn't exist,
+	       - \c B_FIND_PATH_CREATE_DIRECTORY: If a resulting path doesn't
-			create it as a directory (including all missing ancestors).
+	         exist, create it as a directory (including all missing ancestors).
-		- \c B_FIND_PATH_CREATE_PARENT_DIRECTORY: If a resulting path's parent
+	       - \c B_FIND_PATH_CREATE_PARENT_DIRECTORY: If a resulting path's
-			doesn't exist, create the parent directory (including all missing
+	         parent doesn't exist, create the parent directory (including all
-			ancestors).
+	         missing ancestors).
-		- \c B_FIND_PATH_EXISTING_ONLY: If a resulting path doesn't exist, skip
+	       - \c B_FIND_PATH_EXISTING_ONLY: If a resulting path doesn't exist,
-			it. If none of the paths exist, fail with \c B_ENTRY_NOT_FOUND.
+	         skip it. If none of the paths exist, fail with \c B_ENTRY_NOT_FOUND.
 	\param _paths The BStringList variable where the retrieved paths shall be
-		stored. The list is emptied before adding the paths. It is also emptied
+	       stored. The list is emptied before adding the paths. It is also
-		on error.
+	       emptied on error.
+
 	\return A status code.
 	\retval B_OK Everything went fine.
 	\retval B_ENTRY_NOT_FOUND A file system entry required for retrieving the
-		paths doesn't exist. E.g. \c B_FIND_PATH_EXISTING_ONLY was specified and
+	        paths didn't exist, e.g. \c B_FIND_PATH_EXISTING_ONLY was
-		none of the resulting paths do exist.
+	        specified and none of the resulting paths existed.
+
+	\since Haiku R1
 */
 
 
@@ -408,21 +446,25 @@
 	\param baseDirectory Constant indicating which paths to retrieve.
 	\param subPath Relative subpath that shall be appended. Can be \c NULL.
 	\param flags Bitwise OR of any of the following flags:
-		- \c B_FIND_PATH_CREATE_DIRECTORY: If a resulting path doesn't exist,
+	       - \c B_FIND_PATH_CREATE_DIRECTORY: If a resulting path doesn't
-			create it as a directory (including all missing ancestors).
+	         exist, create it as a directory (including all missing ancestors).
-		- \c B_FIND_PATH_CREATE_PARENT_DIRECTORY: If a resulting path's parent
+	       - \c B_FIND_PATH_CREATE_PARENT_DIRECTORY: If a resulting path's
-			doesn't exist, create the parent directory (including all missing
+	         parent doesn't exist, create the parent directory (including all
-			ancestors).
+	         missing ancestors).
-		- \c B_FIND_PATH_EXISTING_ONLY: If a resulting path doesn't exist, skip
+	       - \c B_FIND_PATH_EXISTING_ONLY: If a resulting path doesn't exist,
-			it. If none of the paths exist, fail with \c B_ENTRY_NOT_FOUND.
+	         skip it. If none of the paths exist, fail with
+	         \c B_ENTRY_NOT_FOUND.
 	\param _paths The BStringList variable where the retrieved paths shall be
-		stored. The list is emptied before adding the paths. It is also emptied
+	       stored. The list is emptied before adding the paths. It is also
-		on error.
+	       emptied on error.
+
 	\return A status code.
 	\retval B_OK Everything went fine.
 	\retval B_ENTRY_NOT_FOUND A file system entry required for retrieving the
-		paths doesn't exist. E.g. \c B_FIND_PATH_EXISTING_ONLY was specified and
+	        paths didn't exist, e.g. \c B_FIND_PATH_EXISTING_ONLY was specified
-		none of the resulting paths do exist.
+	        and none of the resulting paths existed.
+
+	\since Haiku R1
 */
 
 
@@ -438,13 +480,16 @@
 	\param baseDirectory Constant indicating which paths to retrieve.
 	\param subPath Relative subpath that shall be appended. Can be \c NULL.
 	\param _paths The BStringList variable where the retrieved paths shall be
-		stored. The list is emptied before adding the paths. It is also emptied
+	       stored. The list is emptied before adding the paths. It is also
-		on error.
+	       emptied on error.
+
 	\return A status code.
 	\retval B_OK Everything went fine.
 	\retval B_ENTRY_NOT_FOUND A file system entry required for retrieving the
-		paths doesn't exist. E.g. \c B_FIND_PATH_EXISTING_ONLY was specified and
+	        paths didn't exist, e.g. \c B_FIND_PATH_EXISTING_ONLY was specified
-		none of the resulting paths do exist.
+	        and none of the resulting paths existed.
+
+	\since Haiku R1
 */
 
 
@@ -459,11 +504,14 @@
 
 	\param baseDirectory Constant indicating which paths to retrieve.
 	\param _paths The BStringList variable where the retrieved paths shall be
-		stored. The list is emptied before adding the paths. It is also emptied
+	       stored. The list is emptied before adding the paths. It is also
-		on error.
+	       emptied on error.
+
 	\return A status code.
 	\retval B_OK Everything went fine.
 	\retval B_ENTRY_NOT_FOUND A file system entry required for retrieving the
-		paths doesn't exist. E.g. \c B_FIND_PATH_EXISTING_ONLY was specified and
+	        paths didn't exist, e.g. \c B_FIND_PATH_EXISTING_ONLY was specified
-		none of the resulting paths do exist.
+	        and none of the resulting paths existed.
+
+	\since Haiku R1
 */

docs/user/storage/Query.dox

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2013 Haiku Inc. All rights reserved.
+ * Copyright 2002-2014 Haiku, Inc. All rights reserved.
  * Distributed under the terms of the MIT License.
  *
  * Authors:
@@ -9,8 +9,8 @@
  *		Ingo Weinhold, [email protected]
  *
  * Corresponds to:
- *		headers/os/storage/Query.h	hrev45283
+ *		headers/os/storage/Query.h	hrev47402
- *		src/kits/storage/Query.cpp	hrev45283
+ *		src/kits/storage/Query.cpp	hrev47402
  */
 
 
@@ -28,6 +28,8 @@
 	\ingroup libbe
 	\brief Provides an interface for creating file system queries and
 	       implements BEntryList methods for iterating through the results.
+
+	\since BeOS R3
 */
 
 
@@ -36,12 +38,16 @@
 	\brief Creates an uninitialized BQuery object.
 
 	\see SetPredicate()
+
+	\since BeOS R3
 */
 
 
 /*!
 	\fn BQuery::~BQuery()
 	\brief Destroys the BQuery object and frees any associated resources.
+
+	\since BeOS R3
 */
 
 
@@ -50,6 +56,8 @@
 	\brief Resets the object to a uninitialized state.
 
 	\return \c B_OK
+
+	\since BeOS R3
 */
 
 
@@ -69,11 +77,13 @@
 	\retval B_NO_INIT The object predicate or the volume wasn't set.
 	\retval B_BAD_VALUE The object predicate was invalid.
 	\retval B_NOT_ALLOWED Fetch() already called.
+
+	\since BeOS R3
 */
 
 
 /*!
-	\name Predicate push methods
+	\name Predicate Push
 
 	Methods to push data onto the predicate stack.
 
@@ -101,6 +111,8 @@
 	\retval B_OK Everything went fine.
 	\retval B_NO_MEMORY Not enough memory.
 	\retval B_NOT_ALLOWED PushAttribute() was called after Fetch().
+
+	\since BeOS R3
 */
 
 
@@ -114,6 +126,8 @@
 	\retval B_OK Everything went fine.
 	\retval B_NO_MEMORY Not enough memory.
 	\retval B_NOT_ALLOWED PushOp() was called after Fetch().
+
+	\since BeOS R3
 */
 
 
@@ -127,6 +141,8 @@
 	\retval B_OK Everything went fine.
 	\retval B_NO_MEMORY Not enough memory.
 	\retval B_NOT_ALLOWED PushUInt32() was called after Fetch().
+
+	\since BeOS R3
 */
 
 
@@ -140,6 +156,8 @@
 	\retval B_OK Everything went fine.
 	\retval B_NO_MEMORY Not enough memory.
 	\retval B_NOT_ALLOWED PushInt32() was called after Fetch().
+
+	\since BeOS R3
 */
 
 
@@ -153,6 +171,8 @@
 	\retval B_OK Everything went fine.
 	\retval B_NO_MEMORY Not enough memory.
 	\retval B_NOT_ALLOWED PushUInt64() was called after Fetch().
+
+	\since BeOS R3
 */
 
 
@@ -166,6 +186,8 @@
 	\retval B_OK Everything went fine.
 	\retval B_NO_MEMORY Not enough memory.
 	\retval B_NOT_ALLOWED PushInt64() was called after Fetch().
+
+	\since BeOS R3
 */
 
 
@@ -179,6 +201,8 @@
 	\retval B_OK Everything went fine.
 	\retval B_NO_MEMORY Not enough memory.
 	\retval B_NOT_ALLOWED PushFloat() was called after Fetch().
+
+	\since BeOS R3
 */
 
 
@@ -192,6 +216,8 @@
 	\retval B_OK Everything went fine.
 	\retval B_NO_MEMORY Not enough memory.
 	\retval B_NOT_ALLOWED PushDouble() was called after Fetch().
+
+	\since BeOS R3
 */
 
 
@@ -207,6 +233,8 @@
 	\retval B_OK Everything went fine.
 	\retval B_NO_MEMORY Not enough memory.
 	\retval B_NOT_ALLOWED PushString() was called after Fetch().
+
+	\since BeOS R3
 */
 
 
@@ -224,6 +252,8 @@
 	\retval B_NOT_ALLOWED PushDate() was called after Fetch().
 
 	\see parsedate()
+
+	\since Haiku R1
 */
 
 
@@ -231,7 +261,7 @@
 
 
 /*!
-	\name Assignment methods
+	\name Assignment
 */
 
 
@@ -252,6 +282,8 @@
 	\return A status code.
 	\retval B_OK Everything went fine.
 	\retval B_NOT_ALLOWED SetVolume() was called after Fetch().
+
+	\since BeOS R3
 */
 
 
@@ -272,6 +304,8 @@
 	\retval B_OK Everything went fine.
 	\retval B_NO_MEMORY Not enough memory.
 	\retval B_NOT_ALLOWED SetPredicate() was called after Fetch().
+
+	\since BeOS R3
 */
 
 
@@ -291,6 +325,8 @@
 	\retval B_OK Everything went fine.
 	\retval B_NO_MEMORY Not enough memory.
 	\retval B_NOT_ALLOWED SetTarget() was called after Fetch().
+
+	\since BeOS R3
 */
 
 
@@ -298,7 +334,7 @@
 
 
 /*!
-	\name Query information methods
+	\name Query Information
 */
 
 
@@ -308,7 +344,12 @@
 /*!
 	\fn bool BQuery::IsLive() const
 	\brief Gets whether the query associated with this object is live.
+
 	\return \c true, if the query is live, \c false otherwise.
+
+	\sa SetTarget()
+
+	\since BeOS R3
 */
 
 
@@ -318,6 +359,10 @@
 
 	\return The device ID of the volume or \c B_NO_INIT if the volume wasn't
 	        set.
+
+	\since BeOS R3
+
+	\since Haiku R1
 */
 
 
@@ -331,6 +376,10 @@
 	SetPredicate().
 
 	\return The length of the predicate string or 0 if an error occurred.
+
+	\see SetPredicate()
+
+	\since BeOS R3
 */
 
 
@@ -338,7 +387,7 @@
 
 
 /*!
-	\name Get predicate methods
+	\name Get Predicate
 
 	These methods fetch a string representation regardless of whether the
 	predicate has been constructed using the predicate stack or via
@@ -364,6 +413,8 @@
 	\retval B_OK Everything went fine.
 	\retval B_NO_INIT The predicate of the BQuery object wasn't set.
 	\retval B_BAD_VALUE \a buffer was \c NULL or too short.
+
+	\since BeOS R3
 */
 
 
@@ -379,6 +430,8 @@
 	\retval B_OK Everything went fine.
 	\retval B_NO_INIT The predicate of the BQuery object wasn't set.
 	\retval B_BAD_VALUE \a predicate was \c NULL.
+
+	\since Haiku R1
 */
 
 
@@ -386,7 +439,7 @@
 
 
 /*!
-	\name BEntryList interface methods
+	\name BEntryList Interface
 
 	These methods are used to traverse the results of a query as a BEntryList.
 
@@ -411,6 +464,8 @@
 	\retval B_ENTRY_NOT_FOUND At end of list.
 	\retval B_BAD_VALUE The predicate included unindexed attributes.
 	\retval B_NOT_ALLOWED Fetch() was not previously called on the object.
+
+	\since BeOS R3
 */
 
 
@@ -426,6 +481,8 @@
 	\retval B_ENTRY_NOT_FOUND At end of list.
 	\retval B_BAD_VALUE The predicate included unindexed attributes.
 	\retval B_NOT_ALLOWED Fetch() was not previously called on the object.
+
+	\since BeOS R3
 */
 
 
@@ -448,6 +505,8 @@
 	        are no more entries to be read, or an error code.
 	\retval B_BAD_VALUE The predicate included unindexed attributes.
 	\retval B_FILE_ERROR Fetch() was not previously called on the object.
+
+	\since BeOS R3
 */
 
 
@@ -460,6 +519,8 @@
 	\return A status code.
 	\retval B_OK Everything went fine.
 	\retval B_FILE_ERROR Fetch() was not previously called on the object.
+
+	\since BeOS R3
 */
 
 
@@ -468,80 +529,9 @@
 	\brief Unimplemented.
 
 	\return \c B_ERROR.
+
+	\since BeOS R3
 */
 
 
 //! @}
-
-
-/// private methods, won't show up in docs
-
-
-/*!
-	\fn bool BQuery::_HasFetched() const
-	\brief Gets whether Fetch() has already been called on this object.
-
-	\return \c true, if Fetch() was already called, \c false otherwise.
-*/
-
-
-/*!
-	\fn status_t BQuery::_PushNode(QueryNode* node, bool deleteOnError)
-	\brief Pushes a node onto the predicate stack.
-
-	If the stack has not been allocate until this time, this method does
-	allocate it.
-
-	If the supplied node is \c NULL, it is assumed that there was not enough
-	memory to allocate the node and thus \c B_NO_MEMORY is returned.
-
-	In case the method fails, the caller retains the ownership of the supplied
-	node and thus is responsible for deleting it, if \a deleteOnError is
-	\c false. If it is \c true, the node is deleted, if an error occurs.
-
-	\param node The node to push.
-	\param deleteOnError Whether or not to delete the node if an error occurs.
-
-	\return A status code.
-	\retval B_OK Everything went fine.
-	\retval B_NO_MEMORY \a node was \c NULL or there was insufficient memory to
-	        allocate the predicate stack or push the node.
-	\retval B_NOT_ALLOWED _PushNode() was called after Fetch().
-*/
-
-
-/*!
-	\fn status_t BQuery::_SetPredicate(const char* expression)
-	\brief Helper method to set the predicate.
-
-	Does not check whether Fetch() has already been invoked.
-
-	\param expression The predicate string to set.
-
-	\return A status code.
-	\retval B_OK Everything went fine.
-	\retval B_NO_MEMORY There was insufficient memory to store the predicate.
-*/
-
-
-/*!
-	\fn status_t BQuery::_EvaluateStack()
-	Evaluates the predicate stack.
-
-	The method does nothing (and returns \c B_OK), if the stack is \c NULL.
-	If the stack is not  \c null and Fetch() has already been called, this
-	method fails.
-
-	\return A status code.
-	\retval B_OK Everything went fine.
-	\retval B_NO_MEMORY There was insufficient memory.
-	\retval B_NOT_ALLOWED _EvaluateStack() was called after Fetch().
-*/
-
-
-/*!
-	\fn void BQuery::_ParseDates(BString& parsedPredicate)
-	\brief Fills out \a parsedPredicate with a parsed predicate string.
-
-	\param parsedPredicate The predicate string to fill out.
-*/

docs/user/storage/Resources.dox

@@ -8,8 +8,8 @@
  *		Ingo Weinhold, [email protected]
  *
  * Corresponds to:
- *		headers/os/storage/Resources.h	hrev45283
+ *		headers/os/storage/Resources.h	hrev47402
- *		src/kits/storage/Resources.cpp	hrev45283
+ *		src/kits/storage/Resources.cpp	hrev47402
  */
 
 
@@ -37,6 +37,8 @@
 	never be invalid. It always serves as a resources container, even if
 	it is not associated with a file. It is always possible to WriteTo()
 	the resources BResources contains to a file (a valid one of course).
+
+	\since BeOS R3
 */
 
 
@@ -45,6 +47,8 @@
 	\brief Creates an uninitialized BResources object.
 
 	\see SetTo()
+
+	\since BeOS R3
 */
 
 
@@ -64,6 +68,8 @@
 
 	\param file The file to create a BResource object from.
 	\param clobber If \c true, the data of the file are erased.
+
+	\since BeOS R3
 */
 
 
@@ -80,6 +86,8 @@
 	\param path A path referring to the file to create a BResource object
 	       from.
 	\param clobber If \c true, the data of the file are erased.
+
+	\since Haiku R1
 */
 
 
@@ -96,6 +104,8 @@
 	\param ref An entry_ref referring to the file to create a BResource object
 	       from.
 	\param clobber If \c true, the data of the file are erased.
+
+	\since Haiku R1
 */
 
 
@@ -105,11 +115,13 @@
 
 	Sync() is first called to make sure that the changes are written back to
 	the file.
+
+	\since BeOS R3
 */
 
 
 /*!
-	\name SetTo methods
+	\name SetTo
 
 	What happens, if \a clobber is \c true, depends on the type of the file.
 	If the file is capable of containing resources, that is, is a resource
@@ -141,6 +153,8 @@
 	\retval B_OK Everything went fine.
 	\retval B_BAD_VALUE \a file was \c NULL or uninitialized.
 	\retval B_ERROR Failed to initialize the object.
+
+	\since BeOS R3
 */
 
 
@@ -158,6 +172,8 @@
 	\retval B_BAD_VALUE \a path was \c NULL.
 	\retval B_ENTRY_NOT_FOUND The file referenced by \a path couldn't be found.
 	\retval B_ERROR Failed to initialize the object.
+
+	\since Haiku R1
 */
 
 
@@ -175,6 +191,8 @@
 	\retval B_BAD_VALUE \a ref was \c NULL.
 	\retval B_ENTRY_NOT_FOUND The file referenced by \a ref couldn't be found.
 	\retval B_ERROR Failed to initialize the object.
+
+	\since Haiku R1
 */
 
 
@@ -192,6 +210,8 @@
 	\retval B_OK Everything went fine.
 	\retval B_ENTRY_NOT_FOUND The file referenced by \a ref couldn't be found.
 	\retval B_ERROR Failed to initialize the object.
+
+	\since Haiku R1
 */
 
 
@@ -215,6 +235,8 @@
 	\retval B_BAD_VALUE \a codeOrDataPointer was \c NULL.
 	\retval B_ENTRY_NOT_FOUND The image or the file couldn't be found.
 	\retval B_ERROR Failed to initialize the object.
+
+	\since Haiku R1
 */
 
 
@@ -222,7 +244,7 @@
 
 
 /*!
-	\name Constructor helper methods
+	\name Constructor Helpers
 */
 
 
@@ -237,6 +259,8 @@
 	written back to the file.
 
 	\note This method is not found in BeOS R5.
+
+	\since Haiku R1
 */
 
 
@@ -253,6 +277,8 @@
 
 	\return \c B_OK if the objects is properly initialized,
 	        \c B_NO_MEMORY otherwise.
+
+	\since Haiku R1
 */
 
 
@@ -260,7 +286,7 @@
 
 
 /*!
-	\name LoadResources methods
+	\name LoadResources
 
 	A resource is loaded into memory only once. A second call with the same
 	parameters will result in the same pointer. The BResources object is the
@@ -283,8 +309,10 @@
 	       shall be written.
 
 	\return A pointer to the resource data if everything went fine, or
-			\c NULL if the file does not have a resource that matches the
+	        \c NULL if the file does not have a resource that matches the
-			parameters or an error occurred.
+	        parameters or an error occurred.
+
+	\since BeOS R4
 */
 
 
@@ -303,8 +331,10 @@
 		   shall be written.
 
 	\return A pointer to the resource data if everything went fine, or
-			\c NULL if the file does not have a resource that matches the
+	        \c NULL if the file does not have a resource that matches the
-			parameters or an error occurred.
+	        parameters or an error occurred.
+
+	\since BeOS R4
 */
 
 
@@ -321,6 +351,8 @@
 	         of errors that occurred.
 	\retval B_OK Everything went fine.
 	\retval B_BAD_FILE The resource map is empty???
+
+	\since BeOS R4
 */
 
 
@@ -332,6 +364,8 @@
 	\brief Gets a reference to the internal BFile object.
 
 	\return A reference to the internal BFile object.
+
+	\since BeOS R4
 */
 
 
@@ -357,6 +391,8 @@
 	\retval B_FILE_ERROR A file error occurred.
 	\retval B_IO_ERROR An error occurred while writing the resources.
 	\retval B_NOT_ALLOWED The file was opened read only.
+
+	\since BeOS R4
 */
 
 
@@ -373,6 +409,8 @@
 	\retval B_BAD_VALUE \a fromFile was \c NULL.
 	\retval B_FILE_ERROR A file error occurred.
 	\retval B_IO_ERROR An error occurred while writing the resources.
+
+	\since BeOS R4
 */
 
 
@@ -389,6 +427,8 @@
 	\param file The file that the resources shall be written to.
 
 	\return \c B_OK if everything went fine or an error code otherwise.
+
+	\since BeOS R4
 */
 
 
@@ -416,6 +456,8 @@
 	\retval B_FILE_ERROR A file error occurred.
 	\retval B_NO_MEMORY Not enough memory for the operation.
 	\retval B_NOT_ALLOWED The file was opened read only.
+
+	\since BeOS R3
 */
 
 
@@ -429,6 +471,8 @@
 
 	\return \c true if the file contains a matching resource,
 	        \c false otherwise.
+
+	\since BeOS R3
 */
 
 
@@ -442,6 +486,8 @@
 
 	\return \c true, if the file contains a matching resource,
 	        \c false otherwise.
+
+	\since BeOS R3
 */
 
 
@@ -462,6 +508,8 @@
 
 	\return \c true, if a matching resource could be found,
 	        \c false otherwise.
+
+	\since BeOS R3
 */
 
 
@@ -482,6 +530,8 @@
 
 	\return \c true, if a matching resource could be found,
 	        \c false otherwise.
+
+	\since BeOS R3
 */
 
 
@@ -500,6 +550,8 @@
 
 	\return \c true, if a matching resource could be found,
 	        \c false otherwise.
+
+	\since BeOS R3
 */
 
 
@@ -518,6 +570,8 @@
 
 	\return \c true, if a matching resource could be found,
 	        \c false otherwise.
+
+	\since BeOS R3
 */
 
 
@@ -540,6 +594,8 @@
 
 	\return \c true, if a matching resource could be found,
 	        \c false otherwise.
+
+	\since BeOS R4
 */
 
 
@@ -557,6 +613,8 @@
 	\retval B_ERROR An error occurred while removing the resource.
 	\retval B_FILE_ERROR A file error occurred.
 	\retval B_NOT_ALLOWED The file was opened read only.
+
+	\since BeOS R4
 */
 
 
@@ -573,11 +631,13 @@
 	\retval B_ERROR An error occurred while removing the resource.
 	\retval B_FILE_ERROR A file error occurred.
 	\retval B_NOT_ALLOWED The file was opened read only.
+
+	\since BeOS R3
 */
 
 
 /*!
-	\name Deprecated methods
+	\name Deprecated Methods
 
 	These methods are deprecated and should not be used as there is a better
 	method. See the method description for the replacement method to use.
@@ -603,7 +663,7 @@
 	\param id The ID of the resource to write data to.
 	\param data The data to be written.
 	\param offset The byte offset relative to the beginning of the resource at
-		   which the data shall be written.
+	       which the data shall be written.
 	\param length The size of the data to be written.
 
 	\return A status code.
@@ -612,6 +672,8 @@
 	        identify an existing resource.
 	\retval B_ERROR Error writing data.
 	\retval B_NO_MEMORY Not enough memory for this operation.
+
+	\since BeOS R3
 */
 
 
@@ -632,7 +694,7 @@
 	\param id The ID of the resource to be read.
 	\param data A pointer to a buffer into which the data shall be read
 	\param offset The byte offset relative to the beginning of the resource
-		   from which the data shall be read.
+	       from which the data shall be read.
 	\param length The size of the data to be read.
 
 	\return A status code.
@@ -641,6 +703,8 @@
 	        identify an existing resource.
 	\retval B_ERROR Error reading data.
 	\retval B_NO_MEMORY Not enough memory for this operation.
+
+	\since BeOS R3
 */
 
 
@@ -658,10 +722,12 @@
 	\param type The type of the resource to find.
 	\param id The ID of the resource to find.
 	\param lengthFound A pointer to a variable into which the size of the
-		   resource data shall be written.
+	       resource data shall be written.
 
 	\return A pointer to the resource data if everything went fine or \c NULL
 	        if an error occurred.
+
+	\since BeOS R3
 */
 
 
@@ -679,10 +745,12 @@
 	\param type The type of the resource to find.
 	\param name The name of the resource to find.
 	\param lengthFound A pointer to a variable into which the size of the
-		   resource data shall be written.
+	       resource data shall be written.
 
 	\return A pointer to the resource data if everything went fine or \c NULL
 	        if an error occurred.
+
+	\since BeOS R3
 */
 
 

docs/user/storage/Statable.dox

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2013 Haiku Inc. All rights reserved.
+ * Copyright 2002-2013 Haiku, Inc. All rights reserved.
  * Distributed under the terms of the MIT License.
  *
  * Authors:
@@ -8,8 +8,8 @@
  *		Ingo Weinhold, [email protected]
  *
  * Corresponds to:
- *		headers/os/storage/Statable.h	hrev45306
+ *		headers/os/storage/Statable.h	hrev47402
- *		src/kits/storage/Statable.cpp	hrev45306
+ *		src/kits/storage/Statable.cpp	hrev47402
  */
 
 
@@ -46,22 +46,26 @@
 	  GetVolume() method.
 	- Get a node_ref of a node to pass into watch_node() via the GetNodeRef()
 	  method.
+
+	\since BeOS R3
 */
 
 
 /*!
-	\fn status_t BStatable::GetStat(struct stat *st) const
+	\fn status_t BStatable::GetStat(struct stat* stat) const
 	\brief Fills out the stat structure for the node.
 
 	This method may be used to access the stat structure of a node directly.
 
-	\param st The stat structure to be filled in.
+	\param stat The stat structure to be filled in.
 
 	\returns A status code.
 	\retval B_OK Everything went fine.
 	\retval B_NO_MEMORY Could not allocate enough memory.
 	\retval B_BAD_VALUE The node does not exist.
 	\retval B_NOT_ALLOWED Node or volume was read only.
+
+	\since BeOS R3
 */
 
 
@@ -71,6 +75,8 @@
 
 	\return \c true, if the node is properly initialized and is a file,
 	        \c false otherwise.
+
+	\since BeOS R5
 */
 
 
@@ -80,6 +86,8 @@
 
 	\return \c true, if the node is properly initialized and is a directory,
 	        \c false otherwise.
+
+	\since BeOS R5
 */
 
 
@@ -89,26 +97,33 @@
 
 	\return \c true, if the node is properly initialized and is a symlink,
 	        \c false otherwise.
+
+	\since BeOS R5
 */
 
 
 /*!
-	\fn status_t BStatable::GetNodeRef(node_ref *ref) const
+	\fn status_t BStatable::GetNodeRef(node_ref* ref) const
 	\brief Fills out \a ref with the \c node_ref of the node.
 
 	\param ref the node_ref to be set.
 
 	\see GetStat() for return codes.
+
+	\since BeOS R3
 */
 
 
 /*!
-	\fn status_t BStatable::GetOwner(uid_t *owner) const
+	\fn status_t BStatable::GetOwner(uid_t* owner) const
 	\brief Fills out the node's UID into \a owner.
 
 	\param owner A pointer to a \c uid_t to be set.
 
+	\see SetOwner()
 	\see GetStat() for return codes.
+
+	\since BeOS R3
 */
 
 
@@ -119,16 +134,21 @@
 	\param owner The UID to set the node to.
 
 	\see GetStat() for return codes.
+
+	\since BeOS R3
 */
 
 
 /*!
-	\fn status_t BStatable::GetGroup(gid_t *group) const
+	\fn status_t BStatable::GetGroup(gid_t* group) const
 	\brief Fills out the node's GID into \a group.
 
 	\param group a pointer to a \c gid_t variable to be set.
 
+	\see SetGroup()
 	\see GetStat() for return codes.
+
+	\since BeOS R3
 */
 
 
@@ -139,47 +159,59 @@
 	\param group The GID to set the node to.
 
 	\see GetStat() for return codes.
+
+	\since BeOS R3
 */
 
 
 /*!
-	\fn status_t BStatable::GetPermissions(mode_t *perms) const
+	\fn status_t BStatable::GetPermissions(mode_t* permissions) const
 	\brief Fills out \a perms with the permissions of the node.
 
-	\param perms A pointer to a \c mode_t variable to be set.
+	\param permissions The permissions to get from the node.
 
+	\see SetPermissions()
 	\see GetStat() for return codes.
+
+	\since BeOS R3
 */
 
 
 /*!
-	\fn status_t BStatable::SetPermissions(mode_t perms)
+	\fn status_t BStatable::SetPermissions(mode_t permissions)
 	\brief Sets the node's permissions to \a perms.
 
-	\param perms The permissions to set the node to.
+	\param permissions The permissions to set the node to.
 
 	\see GetStat() for return codes.
+
+	\since BeOS R3
 */
 
 
 /*!
-	\fn status_t BStatable::GetSize(off_t *size) const
+	\fn status_t BStatable::GetSize(off_t* size) const
 	\brief Fills out the size of the node's data (not counting attributes)
 	       into \a size.
 
 	\param size A pointer to a \c off_t variable to be set.
 
 	\see GetStat() for return codes.
+
+	\since BeOS R3
 */
 
 
 /*!
-	\fn status_t BStatable::GetModificationTime(time_t *mtime) const
+	\fn status_t BStatable::GetModificationTime(time_t* mtime) const
 	\brief Fills out \a mtime with the last modification time of the node.
 
 	\param mtime A pointer to a \c time_t variable to be set.
 
+	\see SetModificationTime()
 	\see GetStat() for return codes.
+
+	\since BeOS R3
 */
 
 
@@ -190,16 +222,21 @@
 	\param mtime The modification time to set the node to.
 
 	\see GetStat() for return codes.
+
+	\since BeOS R3
 */
 
 
 /*!
-	\fn status_t BStatable::GetCreationTime(time_t *ctime) const
+	\fn status_t BStatable::GetCreationTime(time_t* ctime) const
 	\brief Fills out \a ctime with the creation time of the node.
 
 	\param ctime A pointer to a \c time_t variable to be set.
 
+	\see SetCreationTime()
 	\see GetStat() for return codes.
+
+	\since BeOS R3
 */
 
 
@@ -210,15 +247,20 @@
 	\param ctime The creation time to set the node to.
 
 	\see GetStat() for return codes.
+
+	\since BeOS R3
 */
 
 
 /*!
-	\fn status_t BStatable::GetAccessTime(time_t *atime) const
+	\fn status_t BStatable::GetAccessTime(time_t* atime) const
 	\brief Fills out \a atime with the access time of the node.
 
 	\see GetModificationTime()
+	\see SetAccessTime()
 	\see GetStat() for return codes.
+
+	\since BeOS R3
 */
 
 
@@ -228,15 +270,19 @@
 
 	\see GetModificationTime()
 	\see GetStat() for return codes.
+
+	\since BeOS R3
 */
 
 
 /*!
-	\fn status_t BStatable::GetVolume(BVolume *vol) const
+	\fn status_t BStatable::GetVolume(BVolume* volume) const
 	\brief Fills out \a vol with the the volume that the node lives on.
 
-	\param vol A pointer to a BVolume object to be set.
+	\param volume A pointer to a BVolume object to be set.
 
 	\see BVolume
 	\see GetStat() for return codes.
+
+	\since Haiku R1
 */

docs/user/storage/SymLink.dox

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2013 Haiku Inc. All rights reserved.
+ * Copyright 2002-2014 Haiku, Inc. All rights reserved.
  * Distributed under the terms of the MIT License.
  *
  * Authors:
@@ -8,8 +8,8 @@
  *		Ingo Weinhold, [email protected]
  *
  * Corresponds to:
- *		headers/os/storage/SymLink.h	hrev45306
+ *		headers/os/storage/SymLink.h	hrev47402
- *		src/kits/storage/SymLink.cpp	hrev45306
+ *		src/kits/storage/SymLink.cpp	hrev47402
  */
 
 
@@ -27,58 +27,72 @@
 	\ingroup libbe
 	\brief Provides an interface for creating, manipulating, and accessing
 	       the contents of symbolic links.
+
+	\since BeOS R3
 */
 
 
 /*!
 	\fn BSymLink::BSymLink()
 	\brief Creates an uninitialized BSymLink object.
+
+	\since BeOS R3
 */
 
 
 /*!
-	\fn BSymLink::BSymLink(const BSymLink &link)
+	\fn BSymLink::BSymLink(const BSymLink& other)
 	\brief Creates a copy of the supplied BSymLink object.
 
-	\param link The BSymLink object to be copied.
+	\param other The BSymLink object to be copied.
+
+	\since BeOS R3
 */
 
 
 /*!
-	\fn BSymLink::BSymLink(const entry_ref *ref)
+	\fn BSymLink::BSymLink(const entry_ref* ref)
 	\brief Creates a BSymLink object and initializes it to the symbolic link
 	       referred to by the supplied entry_ref.
 
 	\param ref the entry_ref referring to the symbolic link.
+
+	\since BeOS R3
 */
 
 
 /*!
-	\fn BSymLink::BSymLink(const BEntry *entry)
+	\fn BSymLink::BSymLink(const BEntry* entry)
 	\brief Creates a BSymLink object and initializes it to the symbolic link
 	       referred to by the supplied BEntry.
 
 	\param entry The BEntry referring to the symbolic link.
+
+	\since BeOS R3
 */
 
 
 /*!
-	\fn BSymLink::BSymLink(const char *path)
+	\fn BSymLink::BSymLink(const char* path)
 	\brief Creates a BSymLink object and initializes it to the symbolic link
 	       referred to by the supplied path name.
 
 	\param path The path of the symbolic link.
+
+	\since BeOS R3
 */
 
 
 /*!
-	\fn BSymLink::BSymLink(const BDirectory *dir, const char *path)
+	\fn BSymLink::BSymLink(const BDirectory* dir, const char* path)
 	\brief Creates a BSymLink object and initializes it to the symbolic link
 	       referred to by the supplied path name relative to the specified
 	       BDirectory.
 
 	\param dir The base BDirectory.
 	\param path The path of the symbolic link relative to \a dir.
+
+	\since BeOS R3
 */
 
 
@@ -88,11 +102,13 @@
 
 	If the BSymLink was properly initialized, the file descriptor of the
 	symbolic link is also closed.
+
+	\since BeOS R3
 */
 
 
 /*!
-	\fn ssize_t BSymLink::ReadLink(char *buffer, size_t size)
+	\fn ssize_t BSymLink::ReadLink(char* buffer, size_t size)
 	\brief Reads the contents of the symbolic link into \a buffer.
 
 	The string written to the buffer is guaranteed to be \c NULL terminated.
@@ -104,11 +120,13 @@
 	\retval B_BAD_VALUE \a buf was \c NULL or the object didn't refer to a
 	        symbolic link.
 	\retval B_FILE_ERROR The object was not initialized.
+
+	\since BeOS R3
 */
 
 
 /*!
-	\fn ssize_t BSymLink::MakeLinkedPath(const char *dirPath, BPath *path)
+	\fn ssize_t BSymLink::MakeLinkedPath(const char* dirPath, BPath* path)
 	\brief Combines a directory path and the contents of this symbolic link to
 	       form an absolute path.
 
@@ -120,11 +138,13 @@
 	        refer to a symbolic link.
 	\retval B_FILE_ERROR The object was not initialized.
 	\retval B_NAME_TOO_LONG The resulting path name was too long to fit.
+
+	\since BeOS R3
 */
 
 
 /*!
-	\fn ssize_t BSymLink::MakeLinkedPath(const BDirectory *dir, BPath *path)
+	\fn ssize_t BSymLink::MakeLinkedPath(const BDirectory* dir, BPath* path)
 	\brief Combines a directory path and the contents of this symbolic link to
 	       form an absolute path.
 
@@ -136,6 +156,8 @@
 	        refer to a symbolic link.
 	\retval B_FILE_ERROR The object was not initialized.
 	\retval B_NAME_TOO_LONG The resulting path name was too long to fit.
+
+	\since BeOS R3
 */
 
 
@@ -145,15 +167,6 @@
 
 	/return \c true if the object is properly initialized and the symbolic
 	        link refers to an absolute path, \c false otherwise.
-*/
+
-
+	\since BeOS R3
-
-/*!
-	\fn int BSymLink::get_fd() const
-	\brief Returns the file descriptor of the BSymLink.
-
-	This method should be used instead of accessing the private \c fFd member
-	of the BNode directly.
-
-	\return The object's file descriptor, or -1 if not properly initialized.
 */

docs/user/storage/Volume.dox

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2013 Haiku Inc. All rights reserved.
+ * Copyright 2002-2014 Haiku, Inc. All rights reserved.
  * Distributed under the terms of the MIT License.
  *
  * Authors:
@@ -9,8 +9,8 @@
  *		Ingo Weinhold, [email protected]
  *
  * Corresponds to:
- *		headers/os/storage/Volume.h	hrev45306
+ *		headers/os/storage/Volume.h	hrev47402
- *		src/kits/storage/Volume.cpp	hrev45306
+ *		src/kits/storage/Volume.cpp	hrev47402
  */
 
 
@@ -31,6 +31,8 @@
 	The class is a simple wrapper for a \c dev_t and the function
 	fs_stat_dev(). The sole exception is the SetName() method which
 	sets the name of the volume.
+
+	\since BeOS R3
 */
 
 
@@ -41,6 +43,8 @@
 	InitCheck() will return \c B_NO_INIT.
 
 	\see SetTo()
+
+	\since BeOS R3
 */
 
 
@@ -53,11 +57,13 @@
 	successful.
 
 	\param device The device ID of the volume.
+
+	\since BeOS R3
 */
 
 
 /*!
-	\fn BVolume::BVolume(const BVolume &volume)
+	\fn BVolume::BVolume(const BVolume& volume)
 	\brief Creates a copy of the supplied BVolume object.
 
 	Afterwards the object refers to the same device the supplied object
@@ -65,17 +71,21 @@
 	either.
 
 	\param volume The volume object to be copied.
+
+	\since BeOS R3
 */
 
 
 /*!
 	\fn BVolume::~BVolume()
 	\brief Destroys the object and frees all associated resources.
+
+	\since BeOS R3
 */
 
 
 /*!
-	\name Constructor helper methods
+	\name Constructor Helpers
 */
 
 
@@ -88,6 +98,8 @@
 
 	\return \c B_OK if the object was properly initialized, or an error code
 	        otherwise.
+
+	\since BeOS R3
 */
 
 
@@ -97,8 +109,11 @@
 	       the supplied device ID.
 
 	\param device The device ID of the volume to set.
+
 	\return \c B_OK if the object was properly initialized, or an error code
 	        otherwise.
+
+	\since BeOS R3
 */
 
 
@@ -107,6 +122,8 @@
 	\brief Brings the BVolume object to an uninitialized state.
 
 	InitCheck() will return \c B_NO_INIT.
+
+	\since BeOS R3
 */
 
 
@@ -114,7 +131,7 @@
 
 
 /*!
-	\name Volume information methods
+	\name Volume Information
 */
 
 
@@ -126,7 +143,9 @@
 	\brief Returns the device ID of the volume the object refers to.
 
 	\return Returns the device ID of the volume the object refers to
-			or -1 if the object was not properly initialized.
+	        or -1 if the object was not properly initialized.
+
+	\since BeOS R3
 */
 
 
@@ -136,12 +155,14 @@
 	       object into \a directory.
 
 	\param directory A pointer to a pre-allocated BDirectory to be initialized
-		   to the volume's root directory.
+	       to the volume's root directory.
 
 	\return A status code.
 	\retval B_OK Everything went fine.
 	\retval B_BAD_VALUE \a directory was \c NULL or the object was not properly
 	        initialized.
+
+	\since BeOS R3
 */
 
 
@@ -151,6 +172,10 @@
 
 	\return The volume's total storage capacity (in bytes), or \c B_BAD_VALUE
 	        if the object is not properly initialized.
+
+	\see FreeBytes()
+
+	\since BeOS R3
 */
 
 
@@ -160,6 +185,8 @@
 
 	\return The amount of unused space on the volume (in bytes), or
 	        \c B_BAD_VALUE if the object is not properly initialized.
+
+	\since BeOS R3
 */
 
 
@@ -170,6 +197,8 @@
 
 	\return The block size in bytes, \c B_NO_INIT if the volume is not
 	        initialized or other errors forwarded from the file system.
+
+	\since Haiku R1
 */
 
 
@@ -177,7 +206,7 @@
 
 
 /*!
-	\name Volume name methods
+	\name Volume Name
 */
 
 
@@ -196,6 +225,10 @@
 	\retval B_OK Everything went fine.
 	\retval B_BAD_VALUE \a name was \c NULL or the object was not properly
 	        initialized.
+
+	\see SetName()
+
+	\since BeOS R3
 */
 
 
@@ -220,6 +253,8 @@
 	\retval B_OK Everything went fine.
 	\retval B_BAD_VALUE \a name was \c NULL or the object was not properly
 	        initialized.
+
+	\since Haiku R1
 */
 
 
@@ -227,7 +262,7 @@
 
 
 /*!
-	\name Volume icon methods
+	\name Volume Icon
 */
 
 
@@ -239,11 +274,13 @@
 	\brief Writes the volume's icon into the supplied BBitmap.
 
 	\param icon A pointer to a pre-allocated BBitmap of the correct dimension
-		   to store the requested icon (16x16 for the mini and 32x32 for the
+	       to store the requested icon (16x16 for the mini and 32x32 for the
-		   large icon).
+	       large icon).
 
 	\param which The icon size to be retrieved: \c B_MINI_ICON for the mini or
 	       \c B_LARGE_ICON for the large icon.
+
+	\since BeOS R4
 */
 
 
@@ -263,6 +300,8 @@
 
 	\see fs_stat_dev() for more return codes.
 	\see get_device_icon() for more return codes.
+
+	\since Haiku R1
 */
 
 
@@ -270,7 +309,7 @@
 
 
 /*!
-	\name Volume capability methods
+	\name Volume Capabilities
 */
 
 
@@ -283,6 +322,8 @@
 
 	\return \c true, if the volume was properly initialized and is removable,
 	        \c false otherwise.
+
+	\since BeOS R3
 */
 
 
@@ -292,6 +333,8 @@
 
 	\return \c true, if the volume was properly initialized and is read-only,
 	        \c false otherwise.
+
+	\since BeOS R3
 */
 
 
@@ -301,6 +344,8 @@
 
 	\return \c true, if the volume was properly initialized and is persistent,
 	       \c false otherwise.
+
+	\since BeOS R3
 */
 
 
@@ -310,6 +355,8 @@
 
 	return \c true, if the volume was properly initialized and is shared,
 	       \c false otherwise.
+
+	\since BeOS R3
 */
 
 
@@ -319,6 +366,8 @@
 
 	\return \c true, if the volume was properly initialized and supports
 	        MIME-types, \c false otherwise.
+
+	\since BeOS R3
 */
 
 
@@ -328,6 +377,8 @@
 
 	\return \c true, if the volume was properly initialized and supports
 	        attributes, \c false otherwise.
+
+	\since BeOS R3
 */
 
 
@@ -337,6 +388,8 @@
 
 	\return \c true, if the volume was properly initialized and supports
 	        queries, \c false otherwise.
+
+	\since BeOS R3
 */
 
 
@@ -344,7 +397,7 @@
 
 
 /*!
-	\name Operator overload methods
+	\name Operators
 */
 
 
@@ -362,6 +415,8 @@
 	\param volume The volume to be tested for equality.
 
 	\return \c true, if the objects are equal, \c false otherwise.
+
+	\since BeOS R3
 */
 
 
@@ -377,6 +432,8 @@
 	\param volume The volume to be tested for inequality.
 
 	\return \c true, if the objects and unequal, \c false otherwise.
+
+	\since BeOS R3
 */
 
 
@@ -388,6 +445,8 @@
 	\param volume The volume to be assigned.
 
 	\return A reference to this object.
+
+	\since BeOS R3
 */
 
 

docs/user/storage/VolumeRoster.dox

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2013 Haiku Inc. All rights reserved.
+ * Copyright 2002-2014 Haiku, Inc. All rights reserved.
  * Distributed under the terms of the MIT License.
  *
  * Authors:
@@ -8,8 +8,8 @@
  *		Ingo Weinhold, [email protected]
  *
  * Corresponds to:
- *		headers/os/storage/VolumeRoster.h	hrev45306
+ *		headers/os/storage/VolumeRoster.h	hrev47402
- *		src/kits/storage/VolumeRoster.cpp	hrev45306
+ *		src/kits/storage/VolumeRoster.cpp	hrev47402
  */
 
 
@@ -31,12 +31,16 @@
 	This class wraps the next_dev() function for iterating through the
 	list of available volumes and watch_node()/stop_watching() for
 	watching volumes.
+
+	\since BeOS R3
 */
 
 
 /*!
 	\fn BVolumeRoster::BVolumeRoster()
 	\brief Creates a BVolumeRoster object. The object is ready to be used.
+
+	\since BeOS R3
 */
 
 
@@ -45,6 +49,8 @@
 	\brief Deletes the volume roster and frees all associated resources.
 
 	If a watch was activated (by StartWatching()), it is deactivated.
+
+	\since BeOS R3
 */
 
 
@@ -60,6 +66,8 @@
 	\return A status code.
 	\retval B_OK Everything went fine.
 	\retval B_BAD_VALUE The last volume in the list was already returned.
+
+	\since BeOS R3
 */
 
 
@@ -68,6 +76,8 @@
 	\brief Rewinds the list of available volumes back to the first item.
 
 	The next call to GetNextVolume() will return the first available volume.
+
+	\since BeOS R3
 */
 
 
@@ -80,10 +90,12 @@
 	volume is to rename "/boot" -- but, please refrain from doing this.
 
 	\param volume A pointer to a pre-allocated BVolume to be initialized to
-		   refer to the boot volume.
+	       refer to the boot volume.
 
 	\return A status code, \c B_OK if everything went fine or an error code
 	        otherwise.
+
+	\since BeOS R3
 */
 
 
@@ -111,6 +123,8 @@
 	        operation.
 
 	\see watch_node()
+
+	\since BeOS R3
 */
 
 
@@ -119,6 +133,8 @@
 	\brief Stops watching volumes initiated by StartWatching().
 
 	\see stop_watching()
+
+	\since BeOS R3
 */
 
 
@@ -127,5 +143,7 @@
 	\brief Returns the messenger currently watching the volume list.
 
 	\return A messenger to the target currently watching the volume list, or
-			an invalid messenger if not watching.
+	        an invalid messenger if not watching.
+
+	\since BeOS R3
 */