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,12 +46,16 @@
 	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
 */
 
 
@@ -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
 */
 
 
@@ -118,6 +128,8 @@
 	\retval B_BAD_TYPE The attribute/resources the type string is stored in
 	        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.
 
 	\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
 */
 
 
@@ -165,6 +179,8 @@
 	\retval B_BAD_TYPE The attribute/resources the signature is stored in have
 	        the wrong type.
 	\retval B_ENTRY_NOT_FOUND No signature is set on the file.
+
+	\since BeOS R3
 */
 
 
@@ -176,12 +192,14 @@
 
 	\param signature The application signature to be assigned to the file.
 	       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
 */
 
 
@@ -212,6 +230,8 @@
 	\retval B_BAD_TYPE The attribute/resources the entry is stored in have
 	        the wrong type.
 	\retval B_ENTRY_NOT_FOUND No catalog entry is set on the file.
+
+	\since Haiku R1
 */
 
 
@@ -223,7 +243,7 @@
 
 	\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
-		\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.
 
 	\returns a status code.
@@ -231,6 +251,8 @@
 	\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.
+
+	\since Haiku R1
 */
 
 
@@ -259,6 +281,8 @@
 	\retval B_BAD_TYPE The attribute/resources the flags are stored in have
 	        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
 */
 
 
@@ -312,15 +340,17 @@
 	\retval B_BAD_TYPE The attribute/resources that the supported types
 	        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.
 
@@ -347,6 +377,8 @@
 	\returns A status code.
 	\retval B_OK Everything went fine.
 	\retval B_NO_INIT The object is not properly initialized.
+
+	\since BeOS R3
 */
 
 
@@ -379,6 +411,8 @@
 	\returns A status code.
 	\retval B_OK Everything went fine.
 	\retval B_NO_INIT The object is not properly initialized.
+
+	\since BeOS R3
 */
 
 
@@ -394,6 +428,8 @@
 	\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,8 +480,8 @@
 
 /*!
 	\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
@@ -455,6 +495,8 @@
 	\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.
+
+	\since BeOS R3
 */
 
 
@@ -470,6 +512,8 @@
 	\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
 */
 
 
@@ -493,8 +537,11 @@
 	\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.
+
+	\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.
@@ -515,6 +562,8 @@
 	\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.
+
+	\since BeOS R3
 */
 
 
@@ -535,6 +584,8 @@
 	\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
 */
 
 
@@ -555,6 +606,8 @@
 	\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
 */
 
 
@@ -577,8 +630,10 @@
 	\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
 */
 
 
@@ -600,6 +655,8 @@
 	\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.
+
+	\since Haiku R1
 */
 
 
@@ -630,6 +687,8 @@
 	\retval B_BAD_VALUE Either the icon size \a which is unknown,
 	        the bitmap dimensions (\a icon) and icon size (\a which) do not
 	        match, or the provided \a type is not a valid MIME type. 
+
+	\since Haiku R1
 */
 
 
@@ -658,6 +717,8 @@
 	\retval B_BAD_VALUE Either the icon size \a which is unknown,
 	        the bitmap dimensions (\a icon) and icon size (\a which) do not
 	        match, or the provided \a type is not a valid MIME type.
+
+	\since BeOS R3
 */
 
 
@@ -685,6 +746,8 @@
 	\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
 */
 
 
@@ -710,6 +773,8 @@
 	\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,6 +45,8 @@
 	\brief Creates a copy of the supplied BDirectory object.
 
 	\param dir The BDirectory object to be copied.
+
+	\since BeOS R3
 */
 
 
@@ -50,6 +56,8 @@
 	       to by the supplied entry_ref.
 
 	\param ref The entry_ref that refers to the directory.
+
+	\since BeOS R3
 */
 
 
@@ -59,6 +67,8 @@
 	       to by the supplied node_ref.
 
 	\param nref The node_ref that refers to the directory.
+
+	\since BeOS R3
 */
 
 
@@ -68,6 +78,8 @@
 	       to by the supplied BEntry.
 
 	\param entry The BEntry that refers to the directory.
+
+	\since BeOS R3
 */
 
 
@@ -77,6 +89,8 @@
 	       to by the supplied \a path name.
 
 	\param path The \a path name of the directory.
+
+	\since BeOS R3
 */
 
 
@@ -87,6 +101,8 @@
 
 	\param dir The base BDirectory object.
 	\param path The \a path of the directory relative to \a dir
+
+	\since BeOS R3
 */
 
 
@@ -96,6 +112,8 @@
 
 	If the BDirectory is properly initialized, the directory's file descriptor
 	is closed.
+
+	\since BeOS R3
 */
 
 
@@ -116,6 +134,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
 */
 
 
@@ -136,6 +156,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
 */
 
 
@@ -156,6 +178,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
 */
 
 
@@ -178,6 +202,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
 */
 
 
@@ -201,6 +227,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
 */
 
 
@@ -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
 */
 
 
@@ -230,6 +260,8 @@
 
 	\returns \c true if the BDirectory is properly initialized and represents
 	         a root directory of a volume, \c false otherwise.
+
+	\since BeOS R3
 */
 
 
@@ -266,24 +298,28 @@
 	\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.
@@ -294,8 +330,10 @@
 	       - \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
 */
 
 
@@ -319,6 +357,8 @@
 
 	\returns \c true if the BDirectory is properly initialized and the
 	         entry of the matching kind was found, \c false otherwise.
+
+	\since BeOS R3
 */
 
 
@@ -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
 */
 
 
@@ -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
 */
 
 
@@ -393,11 +437,14 @@
 	\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.
 
@@ -413,7 +460,8 @@
 	\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
 */
 
 
@@ -466,6 +518,8 @@
 	\sa BDirectory::GetNextRef()
 	\sa BDirectory::GetNextDirents()
 	\sa BDirectory::Rewind()
+
+	\since BeOS R3
 */
 
 
@@ -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
 */
 
 
@@ -525,6 +581,8 @@
 	\retval B_IS_A_DIRECTORY A directory with the supplied name already
 	        exists.
 	\retval B_NO_MORE_FDS The application has run out of file descriptors.
+
+	\since BeOS R3
 */
 
 
@@ -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
 */
 
 
@@ -600,4 +664,6 @@
 	\retval B_NOT_A_DIRECTORY An entry other than a directory with that name
 	        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,12 +45,16 @@
 	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
 */
 
 
@@ -64,9 +68,11 @@
 	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,6 +81,8 @@
 	\brief Returns a copy of the passed in entry_ref object.
 
 	\param ref A reference to an entry_ref to copy.
+
+	\since BeOS R3
 */
 
 
@@ -82,6 +90,8 @@
 	\fn entry_ref::~entry_ref()
 	\brief Destroys the object and frees the storage allocated for the leaf
 	       name, if necessary.
+
+	\since BeOS R3
 */
 
 
@@ -92,6 +102,8 @@
 
 	\param name Pointer to a null-terminated string containing the new name for
 	       the entry. May be \c NULL.
+
+	\since BeOS R3
 */
 
 
@@ -101,6 +113,8 @@
 	       returning \c true if they are equal.
 
 	\returns \c true if he entry_refs are equal, \c false otherwise.
+
+	\since BeOS R3
 */
 
 
@@ -110,6 +124,8 @@
 	       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
 */
 
 
@@ -290,6 +332,8 @@ BEntry entry("/boot/home/fido");
 	\param traverse Whether or not to traverse symbolic links.
 
 	\returns \c B_OK on success, or an error code on failure.
+
+	\since BeOS R3
 */
 
 
@@ -304,6 +348,8 @@ 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
 */
 
 
@@ -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
 */
 
 
@@ -388,6 +442,8 @@ if (err != B_ENTRY_NOT_FOUND)
 	\retval B_OK Success
 	\retval B_ENTRY_NOT_FOUND Attempted to get the parent of the root
 	        directory.
+
+	\since BeOS R3
 */
 
 
@@ -404,6 +460,8 @@ if (err != B_ENTRY_NOT_FOUND)
 	\retval B_OK Success
 	\retval B_ENTRY_NOT_FOUND Attempted to get the parent of the root
 	        directory.
+
+	\since BeOS R3
 */
 
 
@@ -418,6 +476,8 @@ if (err != B_ENTRY_NOT_FOUND)
 	       is copied.
 
 	\returns \c B_OK on success, or an error code on failure.
+
+	\since BeOS R3
 */
 
 
@@ -430,8 +490,8 @@ if (err != B_ENTRY_NOT_FOUND)
 	      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
 	       exists, it will be overwritten.
@@ -441,6 +501,8 @@ if (err != B_ENTRY_NOT_FOUND)
 	\retval B_ENTRY_EXISTS The new location already exists and \c clobber
 	        is \c false.
 	\retval B_ENTRY_NOT_FOUND Attempted to rename an abstract entry.
+
+	\since BeOS R3
 */
 
 
@@ -456,17 +518,19 @@ if (err != B_ENTRY_NOT_FOUND)
 	\param dir A pointer to a pre-allocated BDirectory into which the entry
 	       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.
 	\retval B_ENTRY_NOT_FOUND Attempted to rename an abstract entry.
+
+	\since BeOS R3
 */
 
 
@@ -480,6 +544,8 @@ 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
 */
 
 
@@ -488,9 +554,12 @@ if (err != B_ENTRY_NOT_FOUND)
 	\brief Returns \c true if the BEntry and \a item refer to the same entry
 	       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.
 	\retval false The BEntry objects refer to different entries.
+
+	\since BeOS R3
 */
 
 
@@ -499,9 +568,12 @@ if (err != B_ENTRY_NOT_FOUND)
 	\brief Returns false if the BEntry and \c item refer to the same entry or
 	       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.
+
+	\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
 */
 
 
@@ -65,6 +71,8 @@
 	\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).
+
+	\since BeOS R3
 */
 
 
@@ -84,6 +92,8 @@
 	\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).
+
+	\since BeOS R3
 */
 
 
@@ -110,6 +120,8 @@
 		there are no more entries to be read.
 	- an error code (depending on the implementation of the derived class)
 		if an error occurred.
+
+	\since BeOS R3
 */
 
 
@@ -120,6 +132,8 @@
 	\retval B_OK if successful
 	\retval B_ERROR or another error code (depending on the implementation
 	        of the derived class).
+
+	\since BeOS R3
 */
 
 
@@ -131,4 +145,6 @@
 	\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).
+
+	\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,6 +61,8 @@
 	If \a file is uninitialized, the newly constructed BFile will be too.
 
 	\param file The BFile object to be copied.
+
+	\since BeOS R3
 */
 
 
@@ -69,6 +75,8 @@
 	\param openMode The mode in which the file should be opened.
 
 	\see SetTo(const entry_ref* ref, uint32 openMode)
+
+	\since BeOS R3
 */
 
 
@@ -81,6 +89,8 @@
 	\param openMode The mode in which the file should be opened.
 
 	\see SetTo(const BEntry* entry, uint32 openMode)
+
+	\since BeOS R3
 */
 
 
@@ -93,6 +103,8 @@
 	\param openMode The mode in which the file should be opened.
 
 	\see SetTo(const char* path, uint32 openMode)
+
+	\since BeOS R3
 */
 
 
@@ -108,6 +120,8 @@
 	\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,6 +130,8 @@
 	\brief Destroys the BFile object and frees all allocated resources.
 
 	If the file is properly initialized, the file descriptor is closed.
+
+	\since BeOS R3
 */
 
 
@@ -131,11 +147,12 @@
 	       - \c B_WRITE_ONLY: The file is opened write only.
 	       - \c B_READ_WRITE: The file is opened for random read/write access.
 	         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_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
+	         size.
 	       - \c B_OPEN_AT_END: Seek() to the end of the file after opening.
 
 	\returns A status code.
@@ -149,6 +166,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
 */
 
 
@@ -174,6 +193,8 @@
 
 	\todo Implemented using SetTo(entry_ref*, uint32). Check, if necessary
 	      to re-implement!
+
+	\since BeOS R3
 */
 
 
@@ -196,7 +217,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
 */
 
 
@@ -226,6 +248,8 @@
 
 	\todo Implemented using SetTo(BEntry*, uint32). Check, if necessary
 	      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,6 +287,8 @@
 	\param size The number of bytes that shall be read.
 
 	\returns The number of bytes read or an error code.
+
+	\since BeOS R3
 */
 
 
@@ -273,6 +303,8 @@
 	\param size The number of bytes that shall be read.
 
 	\returns The number of bytes read or an error code.
+
+	\since BeOS R3
 */
 
 
@@ -284,12 +316,14 @@
 	\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.
 
 	\param location The position (in bytes) within the file at which the data
@@ -298,6 +332,8 @@
 	\param size The number of bytes that shall be written.
 
 	\returns The number of bytes actually written or an error code.
+
+	\since BeOS R3
 */
 
 
@@ -313,14 +349,16 @@
 	\param offset New read/write position, depending on \a seekMode relative
 	       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.
 	\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
 */
 
 
@@ -332,6 +370,8 @@
 	         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
 */
 
 
@@ -353,6 +393,8 @@
 	\retval B_NOT_ALLOWED Trying to set the size of a file on a read only
 	        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
 */
 
 
@@ -84,6 +98,8 @@
 	         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
 */
 
 
@@ -194,17 +212,23 @@
 	       or BHandler controlled by the file panel.
 	\param ref The directory to display, by default the current working
 	       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
+	       only.
 	       - \c B_FILE_NODE Can select files and symlinks to files.
-		- \c B_DIRECTORY_NODE Can select directories and symlinks to directories.
+	       - \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.
+
+	\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,6 +321,8 @@
 	\brief Sets the target messenge.
 
 	\param message The BMessage object to send on confirm.
+
+	\since BeOS R3
 */
 
 
@@ -286,6 +330,8 @@
 	\fn void BFilePanel::Refresh()
 	\brief Refresh the directory or the panel causing the entries to be re-run
 	       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,6 +386,8 @@
 	\brief Set some save text to display in the save dialog.
 
 	\param text The text to display.
+
+	\since BeOS R3
 */
 
 
@@ -341,6 +397,8 @@
 	       by \a ref.
 
 	\param ref The entry contained by the desired panel directory.
+
+	\since BeOS R3
 */
 
 
@@ -350,6 +408,8 @@
 	       by \a path.
 
 	\param path The path of the desired directory.
+
+	\since BeOS R3
 */
 
 
@@ -359,6 +419,8 @@
 	       by \a entry.
 
 	\param entry The BEntry object pointing to the desired directory.
+
+	\since BeOS R3
 */
 
 
@@ -368,6 +430,8 @@
 	       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,15 +488,29 @@
 	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.
 
 	WasHidden() is not called if you call Hide() manually.
+
+	\since BeOS R3
 */
 
 
@@ -434,4 +521,9 @@
 
 	\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,29 +42,34 @@
 	\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.
 */
 
 
@@ -81,13 +90,15 @@
 	       operation is finished, otherwise it returns immediately and the
 	       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_FORCE_KEEP_TYPE
 	       - \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.
+
+	\since BeOS R3
 */
 
 
@@ -110,8 +121,10 @@
 	\param force Entries are created even if they do already exist if not
 	       \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.
+
+	\since BeOS R3
 */
 
 
@@ -124,17 +137,21 @@
 	\param size The size of the icon to retrieve. Currently 16
 	       (\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,
 		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
@@ -143,27 +160,84 @@
 	\param which The size of the icon to retrieve. Currently 16
 	       (\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.
+	\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,
 		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/MimeType.dox

@@ -1,16 +1,15 @@
 /*
- * Copyright 2011 Haiku, Inc. All rights reserved.
+ * Copyright 2011-2014 Haiku, Inc. All rights reserved.
  * Distributed under the terms of the MIT License.
  *
  * Authors:
- *		Tyler Dauwalder
  *		Ingo Weinhold, [email protected]
  *		Axel Dörfler, [email protected]
  *		John Scipione, [email protected]
  *
  * Corresponds to:
- *		headers/os/storage/MimeType.h  hrev43528
+ *		headers/os/storage/MimeType.h  hrev47402
- *		src/kits/storage/MimeType.cpp  hrev43528
+ *		src/kits/storage/MimeType.cpp  hrev47402
  */
 
 
@@ -26,19 +25,23 @@
 	\class BMimeType
 	\ingroup storage
 	\ingroup libbe
-	\brief A class that represents a MIME (Multipurpose Internet Mail
+	\brief A class that represents a MIME (Multi-purpose Internet Mail
 	       Extensions) type string.
 
 	MIME types use, has grown beyond describing the content of email
 	to describe the content types of applications and file formats.
 
-	MIME types consist of a super type and a 
+	MIME types consist of a supertype and a subtype.
+
+	\since BeOS R3
 */
 
 
 /*!
 	\fn BMimeType::BMimeType()
 	\brief Creates an uninitialized BMimeType object.
+
+	\since BeOS R3
 */
 
 
@@ -52,12 +55,16 @@
 	\param mimeType The MIME string.
 
 	\sa SetTo() for further information.
+
+	\since BeOS R3
 */
 
 
 /*!
 	\fn BMimeType::~BMimeType()
 	\brief Frees all resources associated with this object.
+
+	\since BeOS R3
 */
 
 
@@ -85,15 +92,19 @@
 
 	\returns A status code.
 	\retval B_OK Everything went fine.
-	\retval B_NO_INIT \c NULL \a mimeType string.
 	\retval B_BAD_VALUE Invalid \a mimeType string.
+	\retval B_NO_INIT BMimeType was uninitialized.
 	\retval B_NO_MEMORY Insufficient memory to copy the MIME string.
+
+	\since BeOS R3
 */
 
 
 /*!
 	\fn void BMimeType::Unset()
 	\brief Returns the object to an uninitialized state.
+
+	\since BeOS R3
 */
 
 
@@ -103,6 +114,8 @@
 
 	\returns \c B_OK If the object is properly initialized, a specific
 	         error code otherwise.
+
+	\since BeOS R3
 */
 
 
@@ -112,6 +125,8 @@
 
 	\return The MIME string, if the object is properly initialized, \c NULL
 	        otherwise.
+
+	\since BeOS R3
 */
 
 
@@ -123,6 +138,8 @@
 	        otherwise.
 
 	\sa SetTo() for further information.
+
+	\since BeOS R3
 */
 
 
@@ -132,6 +149,8 @@
 
 	\return \c true, if the object is properly initialized and represents a
 	        supertype, \c false otherwise.
+
+	\since BeOS R3
 */
 
 
@@ -143,27 +162,32 @@
 	To add the MIME type to the database, call \c Install().
 	To remove the MIME type from the database, call \c Delete().
 
-	\returns A \c bool indicating whether or not this type is currently
+	\return A \c bool indicating whether or not this type is currently
 	        installed in the MIME database.
 	\retval true The MIME type is currently installed in the database.
 	\retval false The MIME type is not currently installed in the database.
+
+	\since BeOS R3
 */
 
 
 /*!
-	\fn status_t BMimeType::GetSupertype(BMimeType *superType) const
+	\fn status_t BMimeType::GetSupertype(BMimeType* supertype) const
-	\brief Gets the supertype of the MIME type represented by this object.
+	\brief Gets the \a supertype of the MIME type represented by this object.
 
-	The supplied object is initialized to this object's supertype. If this
+	The supplied object is initialized to this object's \a supertype. If this
 	BMimeType is not properly initialized, the supplied object will be Unset().
 
-	\param superType A pointer to the BMimeType object that shall be
+	\param supertype A pointer to the BMimeType object that shall be
-		   initialized to this object's supertype.
+	       initialized to this object's \a supertype.
 
 	\returns A status code.
 	\retval B_OK Everything went fine.
 	\retval B_BAD_VALUE \c NULL \a superType, this object is not initialized,
 	        or this object is a supertype only.
+	\retval B_NO_INIT BMimeType was uninitialized.
+
+	\since BeOS R3
 */
 
 
@@ -180,6 +204,8 @@
 	\param type The BMimeType to be compared with.
 
 	\return \c true, if the objects are equal, \c false otherwise.
+
+	\since BeOS R3
 */
 
 
@@ -197,6 +223,8 @@
 	\param type The MIME string to be compared with.
 
 	\return \c true, if the MIME types are equal, \c false otherwise.
+
+	\since BeOS R4
 */
 
 
@@ -209,6 +237,8 @@
 
 	\returns \c true, if this MIME type is a supertype of or equals the
 	         supplied one, \c false otherwise.
+
+	\since BeOS R3
 */
 
 
@@ -223,6 +253,10 @@
 	installed, so be sure to check \c IsInstalled() first.
 
 	\returns \c B_OK on success or another error code on failure.
+
+	\see Delete()
+
+	\since BeOS R3
 */
 
 
@@ -234,10 +268,12 @@
 	To add the MIME type to the database, call \c Install().
 
 	\note Calling \c BMimeType::Delete() does not uninitialize or otherwise
-	deallocate the \c BMimeType object; it simply removes the type from the
+	      deallocate the \c BMimeType object; it simply removes the type from
-	database.
+	      the database.
 
 	\returns \c B_OK on success or another error code on failure.
+
+	\since BeOS R3
 */
 
 
@@ -257,8 +293,11 @@
 
 	\returns A status code.
 	\retval B_OK Everything went fine.
-	\retval B_ENTRY_NOT_FOUND: No icon of the given size exists for the
+	\retval B_ENTRY_NOT_FOUND No icon of the given size exists for the
 	        given type.
+	\retval B_NO_INIT BMimeType was uninitialized.
+
+	\since BeOS R3
 */
 
 
@@ -274,8 +313,11 @@
 
 	\returns A status code.
 	\retval B_OK Everything went fine.
-	\retval B_ENTRY_NOT_FOUND No icon of the given size exists for the given
+	\retval B_ENTRY_NOT_FOUND No icon of the given size found for the given
-		type
+	        type.
+	\retval B_NO_INIT BMimeType was uninitialized.
+
+	\since BeOS R3
 */
 
 
@@ -301,10 +343,16 @@
 	\param verb \c app_verb value that specifies the type of access for
 		which you are requesting the preferred app. Currently, the only
 		supported app verb is \c B_OPEN.
+
 	\returns A status code.
 	\retval B_OK Success
 	\retval B_ENTRY_NOT_FOUND No preferred app exists for the given type
 	        and app_verb.
+	\retval B_NO_INIT BMimeType was uninitialized.
+
+	\see SetPreferredApp()
+
+	\since BeOS R3
 */
 
 
@@ -360,6 +408,10 @@
 	       the MIME type's associated file attributes is stored.
 
 	\returns \c B_OK on success or another error code on failure.
+
+	\see SetAttrInfo()
+
+	\since BeOS R3
 */
 
 
@@ -393,6 +445,10 @@
 	       MIME type's associated file extensions will be stored.
 
 	\returns \c B_OK on success or another error code on failure.
+
+	\see SetFileExtensions()
+
+	\since BeOS R3
 */
 
 
@@ -410,7 +466,12 @@
 
 	\returns A status code.
 	\retval B_OK Success
-	\retval B_ENTRY_NOT_FOUND No short description exists for the given type
+	\retval B_ENTRY_NOT_FOUND No short description exists for the given type.
+	\retval B_NO_INIT BMimeType was uninitialized.
+
+	\see SetShortDescription()
+
+	\since BeOS R3
 */
 
 
@@ -429,6 +490,11 @@
 	\returns A status code.
 	\retval B_OK Success
 	\retval B_ENTRY_NOT_FOUND No long description exists for the given type.
+	\retval B_NO_INIT BMimeType was uninitialized.
+
+	\see SetLongDescription()
+
+	\since BeOS R3
 */
 
 
@@ -486,7 +552,11 @@
 	\param signatures Pointer to a pre-allocated BMessage into which the
 	       signatures of the supporting applications will be copied.
 
-	\returns \c B_OK on success or another error code on failure.
+	\returns \c B_OK on success or an error code on failure.
+
+	\see SetSupportingApps()
+
+	\since BeOS R3
 */
 
 
@@ -508,6 +578,8 @@
 	       \c B_LARGE_ICON and \c B_MINI_ICON are supported.
 
 	\returns \c B_OK on success or another error code on failure.
+
+	\since BeOS R3
 */
 
 
@@ -525,6 +597,8 @@
 	\param size Size of the provided buffer.
 
 	\returns \c B_OK on success or another error code on failure.
+
+	\since Haiku R1
 */
 
 
@@ -552,6 +626,8 @@
 	       supported app verb is \c B_OPEN.
 
 	\returns \c B_OK on success or another error code on failure.*/
+
+	\since BeOS R3
 */
 
 
@@ -601,10 +677,12 @@
 	The \c BMessage::what value is ignored.
 
 	\param info Pointer to a pre-allocated and properly formatted BMessage
-		containing  information about the file attributes typically associated
+	       containing information about the file attributes typically
-		with the MIME type.
+	       associated with the MIME type.
 
 	\returns \c B_OK on success or another error code on failure.
+
+	\since BeOS R3
 */
 
 
@@ -625,12 +703,12 @@
 	  not \c ".html" or \c ".mp3" ).
 	- The \c what member of the BMessage is ignored.
 
-	\note any other fields present in the \c BMessage will currently be retained
+	\note Any other fields present in the \c BMessage will currently be
-	and returned by calls to \c GetFileExtensions(); however, this may change in
+	      retained and returned by calls to \c GetFileExtensions(); however,
-	the future, so it is recommended that you not rely on this behaviour, and
+	      this may change in the future, so it is recommended that you not rely
-	that no other fields be present. Also, note that no checking is performed to
+	      on this behavior, and that no other fields be present. Also, note that
-	verify the \c BMessage is properly formatted; it's up to you to do things
+	      no checking is performed to verify the \c BMessage is properly
-	right.
+	      formatted; it's up to you to do things right.
 
 	Finally, bear in mind that \c SetFileExtensions() clobbers the existing set
 	of extensions. If you want to augment a type's extensions, you should
@@ -638,10 +716,12 @@
 	\c SetFileExtensions().
 
 	\param extensions Pointer to a pre-allocated, properly formatted BMessage
-		containing the new list of file extensions to associate with this MIME
+	       containing the new list of file extensions to associate with this
-		type.
+	       MIME type.
 
 	\returns \c B_OK on success or another error code on failure.
+
+	\since BeOS R3
 */
 
 
@@ -659,6 +739,8 @@
 	       new short description.
 
 	\returns \c B_OK on success or another error code on failure.
+
+	\since BeOS R3
 */
 
 
@@ -676,21 +758,25 @@
 	       long description
 
 	\returns \c B_OK on success or another error code on failure.
+
+	\since BeOS R3
 */
 
 
 /*!
 	\fn status_t BMimeType::GetInstalledSupertypes(BMessage* supertypes)
-	\brief Fetches a BMessage listing all the MIME supertypes currently
+	\brief Fetches a BMessage listing all the MIME \a supertypes currently
 	       installed in the MIME database.
 
 	The types are copied into the \c "super_types" field of the passed-in
 	\c BMessage. The \c BMessage must be pre-allocated.
 
 	\param supertypes Pointer to a pre-allocated \c BMessage into which the
-	                  MIME supertypes will be copied.
+	       MIME \a supertypes will be copied.
 
 	\returns \c B_OK on success or another error code on failure.
+
+	\since BeOS R3
 */
 
 
@@ -706,6 +792,8 @@
 	       MIME types will be copied.
 
 	\returns \c B_OK on success or another error code on failure.
+
+	\since BeOS R3
 */
 
 
@@ -713,17 +801,19 @@
 	\fn status_t BMimeType::GetInstalledTypes(const char* supertype,
 		BMessage* types)
 	\brief Fetches a BMessage listing all the MIME subtypes of the given
-		supertype currently installed in the MIME database.
+	       \a supertype currently installed in the MIME database.
 
-	The types are copied into the \c "types" field of the passed-in \c BMessage.
+	The types are copied into the \c "types" field of the passed-in
-	The \c BMessage must be pre-allocated.
+	\c BMessage. The \c BMessage must be pre-allocated.
 
-	\param supertype Pointer to a string containing the MIME supertype whose
+	\param supertype Pointer to a string containing the MIME \a supertype whose
 	       subtypes you wish to retrieve.
 	\param types Pointer to a pre-allocated \c BMessage into which the
 	       appropriate MIME subtypes will be copied.
 
 	\returns \c B_OK on success or another error code on failure.
+
+	\since BeOS R3
 */
 
 
@@ -744,6 +834,8 @@
 
 	\sa GetSupportingApps() for details on the format of the data returned in
 	    the \c BMessage pointed to by \c wild_ones.
+
+	\since BeOS R3
 */
 
 
@@ -756,8 +848,9 @@
 	\return \c true, if the given string represents a valid MIME type.
 
 	\sa SetTo() for further information.
-*/
 
+	\since BeOS R3
+*/
 
 
 /*!
@@ -779,10 +872,12 @@
 	       of the app hint is copied. If the function fails, the contents of
 	       the \c entry_ref are undefined.
 
-	\return
+	\return A status code, B_OK on success or an error code otherwise.
-	- \c B_OK: Success
+	\retval B_OK The ref was retrieved successfully.
-	- \c B_ENTRY_NOT_FOUND: No app hint exists for the given type
+	\retval B_ENTRY_NOT_FOUND No app hint existed for the given \a ref.
-	- other error code: Failure
+	\retval B_NO_INIT BMimeType was uninitialized.
+
+	\since BeOS R3
 */
 
 
@@ -808,6 +903,12 @@
 	       of the new app hint
 
 	\returns \c B_OK on success or another error code on failure.
+	\retval B_OK The ref was retrieved successfully.
+	\retval B_NO_INIT BMimeType was uninitialized.
+	\retval B_BAD_VALUE \a ref was \c NULL.
+	\retval B_NO_INIT BMimeType was uninitialized.
+
+	\since BeOS R3
 */
 
 
@@ -841,10 +942,13 @@
 	\param which Value that specifies which icon to return. Currently
 	       \c B_LARGE_ICON and \c B_MINI_ICON are supported.
 
-	\returns A status code.
+	\returns A status code, \c B_OK on success or an error code otherwise.
 	\retval B_OK Success
 	\retval B_ENTRY_NOT_FOUND No icon of the given size exists for the
-			given type
+	        given type.
+	\retval B_NO_INIT BMimeType was uninitialized.
+
+	\since BeOS R3
 */
 
 
@@ -862,12 +966,15 @@
 	\param _data Pointer in which the allocated icon data is returned. You need
 	       to delete the buffer when you are done with it.
 	\param _size Pointer in which the size of the allocated icon data is
-				returned.
+	       filled out.
 
-	\returns A status code.
+	\returns A status code, \c B_OK on success or an error code otherwise.
-	\retval B_OK Success
+	\retval B_OK Success.
 	\retval B_ENTRY_NOT_FOUND No icon of the given size exists for the
 	        given type.
+	\retval B_NO_INIT BMimeType was uninitialized.
+
+	\since Haiku R1
 */
 
 
@@ -897,12 +1004,14 @@
 	\param type Pointer to a pre-allocated string containing the MIME type whose
 	       custom icon you wish to set.
 	\param icon Pointer to a pre-allocated \c BBitmap of proper size and
-				colorspace containing the new icon, or \c NULL to clear the
+	       colorspace containing the new icon, or \c NULL to clear the current
-				current icon.
+	       icon.
 	\param which Value that specifies which icon to update. Currently
 	       \c B_LARGE_ICON and \c B_MINI_ICON are supported.
 
 	\returns \c B_OK on success or another error code on failure.
+
+	\since BeOS R3
 */
 
 
@@ -939,6 +1048,8 @@
 	       \c B_LARGE_ICON and \c B_MINI_ICON are supported.
 
 	\returns \c B_OK on success or another error code on failure.
+
+	\since Haiku R1
 */
 
 
@@ -953,6 +1064,11 @@
 	\retval B_OK Everything went fine.
 	\retval B_BAD_VALUE \c NULL \a result or uninitialized BMimeType.
 	\retval B_ENTRY_NOT_FOUND The MIME type is not installed.
+	\retval B_NO_INIT BMimeType was uninitialized.
+
+	\see SetSnifferRule()
+
+	\since Haiku R1
 */
 
 
@@ -972,8 +1088,11 @@
 	\retval B_OK Everything went fine.
 	\retval B_BAD_VALUE Uninitialized BMimeType.
 	\retval B_BAD_MIME_SNIFFER_RULE The supplied sniffer rule is invalid.
+	\retval B_NO_INIT BMimeType was uninitialized.
 
-	\sa CheckSnifferRule().
+	\sa CheckSnifferRule()
+
+	\since Haiku R1
 */
 
 
@@ -1063,6 +1182,9 @@
 	\retval B_BAD_VALUE \c NULL \a rule.
 	\retval B_BAD_MIME_SNIFFER_RULE The supplied sniffer rule is not valid. A
 	        description of the error is written to \a parseError, if supplied.
+	\retval B_NO_INIT BMimeType was uninitialized.
+
+	\since Haiku R1
 */
 
 
@@ -1085,6 +1207,9 @@
 	\retval B_OK Everything went fine.
 	\retval B_BAD_VALUE \c NULL \a ref or \a result.
 	\retval B_NAME_NOT_FOUND \a ref refers to an abstract entry.
+	\retval B_NO_INIT BMimeType was uninitialized.
+
+	\since Haiku R1
 */
 
 
@@ -1101,6 +1226,9 @@
 	\returns A status code.
 	\retval B_OK Everything went fine.
 	\retval B_BAD_VALUE \c NULL \a buffer or \a result.
+	\retval B_NO_INIT BMimeType was uninitialized.
+
+	\since Haiku R1
 */
 
 
@@ -1119,6 +1247,9 @@
 	\returns A status code.
 	\retval B_OK Everything went fine.
 	\retval B_BAD_VALUE \c NULL \a ref or \a result.
+	\retval B_NO_INIT BMimeType was uninitialized.
+
+	\since Haiku R1
 */
 
 
@@ -1132,6 +1263,8 @@
 	\param target A BMessenger identifying the target for the update messages.
 
 	\returns \c B_OK on success or another error code on failure.
+
+	\since BeOS R4
 */
 
 
@@ -1143,6 +1276,8 @@
 	\param target A BMessenger identifying the target for the update messages.
 
 	\returns \c B_OK on success or another error code on failure.
+
+	\since BeOS R4
 */
 
 
@@ -1152,57 +1287,6 @@
 
 	\deprecated This method has the same semantics as SetTo().
 	            Use SetTo() instead.
+
+	\since BeOS R3
 */
-
-
-/*!
-	\fn status_t BMimeType::SetSupportedTypes(const BMessage *types,
-		bool fullSync)
-	\brief Sets the list of MIME types supported by the MIME type (which is
-		assumed to be an application signature).
-
-	If \a types is \c NULL the application's supported types are unset.
-
-	The supported MIME types must be stored in a field "types" of type
-	\c B_STRING_TYPE in \a types.
-
-	For each supported type the result of BMimeType::GetSupportingApps() will
-	afterwards include the signature of this application. 
-
-	\a fullSync specifies whether or not any types that are no longer
-	listed as supported types as of this call to SetSupportedTypes() shall be
-	updated as well, i.e. whether this application shall be removed from their
-	lists of supporting applications.
-	
-	If \a fullSync is \c false, this application will not be removed from the
-	previously supported types' supporting apps lists until the next call
-	to BMimeType::SetSupportedTypes() or BMimeType::DeleteSupportedTypes()
-	with a \c true \a fullSync parameter, the next call to BMimeType::Delete(),
-	or the next reboot.
-
-	\param types The supported types to be assigned to the file.
-				 May be \c NULL.
-	\param fullSync \c true to also synchronize the previously supported
-					types, \c false otherwise.
-
-	\returns \c B_OK on success or another error code on failure.
-*/
-
-
-/*!
-	\fn status_t BMimeType::GetAssociatedTypes(const char *extension,
-		BMessage *types)
-	\brief Returns a list of mime types associated with the given file extension
-
-	The list of types is returned in the pre-allocated \c BMessage pointed to
-	by \a types. The types are stored in the message's "types" field, which
-	is an array of \c B_STRING_TYPE values.
-	
-	\param extension The file extension of interest
-	\param types Pointer to a pre-allocated BMessage into which the result will
-	             be stored
-	             
-	\returns \c B_OK on success or another error code on failure.
-*/
-
-

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,34 +134,18 @@
 	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
 */
 
 
@@ -119,7 +154,9 @@
 	\brief Creates a BNode object and initializes it to the specified
 	       entry_ref.
 
-	\param ref the entry_ref referring to the entry.
+	\param ref The entry_ref referring to the node.
+
+	\since BeOS R3
 */
 
 
@@ -128,7 +165,9 @@
 	\brief Creates a BNode object and initializes it to the specified
 	       filesystem entry.
 
-	\param entry the BEntry representing the entry.
+	\param entry The BEntry referring to the node.
+
+	\since BeOS R3
 */
 
 
@@ -137,7 +176,9 @@
 	\brief Creates a BNode object and initializes it to the entry referred
 	       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
 */
 
 
@@ -146,44 +187,43 @@
 	\brief Creates a BNode object and initializes it to the entry referred
 	       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.
 
-	\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,12 +249,13 @@
 
 
 /*!
-	\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
 */
 
 
@@ -220,12 +263,15 @@
 	\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
 */
 
 
@@ -233,12 +279,33 @@
 	\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 \a entry could not be found.
+	\retval B_BUSY The \a entry was locked.
+
+	\since BeOS R3
+*/
+
+
+/*!
+	\fn status_t BNode::SetTo(const char* path)
+	\brief Initializes the object to the specified \a path.
+
+	\param path The entry's path name; \a path can be relative or absolute,
+	       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 \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
 */
 
 
@@ -247,19 +314,24 @@
 	\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 dir The base BDirectory.
-	\param path the entry's path name relative to \a dir
+	\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 \c NULL \a entry.
+	\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 is locked.
+	\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
 */
 
 
@@ -279,9 +351,12 @@
 	\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.
 
+	\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
 */
 
 
@@ -317,48 +398,54 @@
 
 /*!
 	\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,
-								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
 */
 
 
@@ -366,32 +453,38 @@
 	\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
 */
 
 
@@ -401,13 +494,16 @@
 	\brief Fills in the pre-allocated attr_info struct pointed to by \a info
 	       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
 */
 
 
@@ -418,18 +514,21 @@
 
 	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.
-	\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
 */
 
 
@@ -438,8 +537,11 @@
 	\brief Resets the object's attribute pointer to the first attribute in the
 	       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
 */
 
 
@@ -451,13 +553,18 @@
 	\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
 */
 
 
@@ -469,10 +576,13 @@
 	\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
 */
 
 
@@ -40,6 +42,8 @@
 	After created a BNodeInfo with this, you should call SetTo().
 
 	\see SetTo(BNode* node)
+
+	\since BeOS R3
 */
 
 
@@ -48,7 +52,9 @@
 	\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
 */
 
 
@@ -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
 */
 
 
@@ -125,6 +137,8 @@
 	        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
 */
 
 
@@ -136,7 +150,7 @@
 	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,7 +177,7 @@
 
 
 /*!
-	\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
@@ -170,7 +186,7 @@
 	\param icon A pointer to a pre-allocated BBitmap object of the correct
 	       dimension to store the requested icon: 16x16 for the mini or
 	       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.
@@ -178,11 +194,13 @@
 	\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.
+
+	\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.
 
@@ -192,7 +210,7 @@
 
 	\param icon A pointer to a BBitmap object containing the icon to be set.
 	       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.
@@ -200,6 +218,8 @@
 	\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.
+
+	\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,
-		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
@@ -278,42 +302,46 @@
 	\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 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 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,
-		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
 */
 
 
@@ -379,7 +407,7 @@
 
 
 /*!
-	\name Application hint methods
+	\name Application Hint
 */
 
 

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,6 +331,8 @@
 	\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
 */
 
 
@@ -303,6 +365,8 @@
 	\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
 */
 
 
@@ -341,6 +405,8 @@
 	\param target BMessenger object referring to the \a target.
 
 	\return \c B_OK if everything went fine, an error code otherwise.
+
+	\since BeOS R3
 */
 
 
@@ -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,6 +471,8 @@
 	\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
 */
 
 
@@ -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
 */
 
 
@@ -54,22 +57,24 @@
 
 	\param codePointer A pointer to code or static data belonging to the image
 	       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).
+
+	\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,8 +85,10 @@
 	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
 */
 
 
@@ -96,32 +103,37 @@
 
 	\param ref A reference to be resolved to 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.
 
 	\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
 */
 
 
@@ -132,11 +144,12 @@
 	       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
@@ -148,24 +161,27 @@
 
 	\param codePointer A pointer to code or static data belonging to the image
 	       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).
+
 	\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
@@ -179,8 +195,10 @@
 	\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.
-	\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
 */
 
 
@@ -195,10 +213,14 @@
 
 	\param ref A reference to be resolved to 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.
 
 	\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,
 	         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
-		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,
 	         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
-		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
@@ -285,6 +311,8 @@
 	\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
 	        parameters or an error occurred.
+
+	\since BeOS R4
 */
 
 
@@ -305,6 +333,8 @@
 	\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
 	        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.
@@ -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
 */
 
 
@@ -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
 */
 
 
@@ -662,6 +726,8 @@
 
 	\return A pointer to the resource data if everything went fine or \c NULL
 	        if an error occurred.
+
+	\since BeOS R3
 */
 
 
@@ -683,6 +749,8 @@
 
 	\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,6 +97,8 @@
 
 	\return \c true, if the node is properly initialized and is a symlink,
 	        \c false otherwise.
+
+	\since BeOS R5
 */
 
 
@@ -99,6 +109,8 @@
 	\param ref the node_ref to be set.
 
 	\see GetStat() for return codes.
+
+	\since BeOS R3
 */
 
 
@@ -108,7 +120,10 @@
 
 	\param owner A pointer to a \c uid_t to be set.
 
+	\see SetOwner()
 	\see GetStat() for return codes.
+
+	\since BeOS R3
 */
 
 
@@ -119,6 +134,8 @@
 	\param owner The UID to set the node to.
 
 	\see GetStat() for return codes.
+
+	\since BeOS R3
 */
 
 
@@ -128,7 +145,10 @@
 
 	\param group a pointer to a \c gid_t variable to be set.
 
+	\see SetGroup()
 	\see GetStat() for return codes.
+
+	\since BeOS R3
 */
 
 
@@ -139,26 +159,33 @@
 	\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
 */
 
 
@@ -170,6 +197,8 @@
 	\param size A pointer to a \c off_t variable to be set.
 
 	\see GetStat() for return codes.
+
+	\since BeOS R3
 */
 
 
@@ -179,7 +208,10 @@
 
 	\param mtime A pointer to a \c time_t variable to be set.
 
+	\see SetModificationTime()
 	\see GetStat() for return codes.
+
+	\since BeOS R3
 */
 
 
@@ -190,6 +222,8 @@
 	\param mtime The modification time to set the node to.
 
 	\see GetStat() for return codes.
+
+	\since BeOS R3
 */
 
 
@@ -199,7 +233,10 @@
 
 	\param ctime A pointer to a \c time_t variable to be set.
 
+	\see SetCreationTime()
 	\see GetStat() for return codes.
+
+	\since BeOS R3
 */
 
 
@@ -210,6 +247,8 @@
 	\param ctime The creation time to set the node to.
 
 	\see GetStat() for return codes.
+
+	\since BeOS R3
 */
 
 
@@ -218,7 +257,10 @@
 	\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,20 +27,26 @@
 	\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
 */
 
 
@@ -50,6 +56,8 @@
 	       referred to by the supplied entry_ref.
 
 	\param ref the entry_ref referring to the symbolic link.
+
+	\since BeOS R3
 */
 
 
@@ -59,6 +67,8 @@
 	       referred to by the supplied BEntry.
 
 	\param entry The BEntry referring to the symbolic link.
+
+	\since BeOS R3
 */
 
 
@@ -68,6 +78,8 @@
 	       referred to by the supplied path name.
 
 	\param path The path of the symbolic link.
+
+	\since BeOS R3
 */
 
 
@@ -79,6 +91,8 @@
 
 	\param dir The base BDirectory.
 	\param path The path of the symbolic link relative to \a dir.
+
+	\since BeOS R3
 */
 
 
@@ -88,6 +102,8 @@
 
 	If the BSymLink was properly initialized, the file descriptor of the
 	symbolic link is also closed.
+
+	\since BeOS R3
 */
 
 
@@ -104,6 +120,8 @@
 	\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
 */
 
 
@@ -120,6 +138,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
 */
 
 
@@ -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,6 +57,8 @@
 	successful.
 
 	\param device The device ID of the volume.
+
+	\since BeOS R3
 */
 
 
@@ -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
 */
 
 
@@ -127,6 +144,8 @@
 
 	\return Returns the device ID of the volume the object refers to
 	        or -1 if the object was not properly initialized.
+
+	\since BeOS R3
 */
 
 
@@ -142,6 +161,8 @@
 	\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
 */
 
 
@@ -244,6 +279,8 @@
 
 	\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
 */
 
 
@@ -84,6 +94,8 @@
 
 	\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
 */
 
 
@@ -128,4 +144,6 @@
 
 	\return A messenger to the target currently watching the volume list, or
 	        an invalid messenger if not watching.
+
+	\since BeOS R3
 */