Storage Kit: Style fixes to mime database

* Update doxygen docs a bit, especially returns.
* Some variable renaming for consistency and clarity, err/error => result.
* Remove some dead code that isn't coming back. (code moved to IconUtils)
* OpenType() returns a status_t, put it in a status_t, not a ssize_t.
  and then later create a new ssize_t to hold the read bytes read
  and use that, saves a lot of casting and confusion.

src/kits/storage/mime/DatabaseLocation.cpp

@@ -1,11 +1,11 @@
 /*
- * Copyright 2002-2014, Haiku, Inc. All Rights Reserved.
+ * Copyright 2002-2014 Haiku, Inc. All Rights Reserved.
  * Distributed under the terms of the MIT License.
  *
  * Authors:
  *		Tyler Dauwalder
- *		Rene Gollent, [email protected].
+ *		Rene Gollent, [email protected]
- *		Ingo Weinhold <[email protected]>
+ *		Ingo Weinhold, [email protected]
  */
 
 
@@ -53,8 +53,9 @@ DatabaseLocation::AddDirectory(const BString& directory)
 }
 
 
-/*! \brief Opens a BNode on the given type, failing if the type has no
+/*!	Opens a BNode on the given type, failing if the type has no
 	corresponding file in the database.
+
 	\param type The MIME type to open.
 	\param _node Node opened on the given MIME type.
 */
@@ -69,14 +70,18 @@ DatabaseLocation::OpenType(const char* type, BNode& _node) const
 }
 
 
-/*! \brief Opens a BNode on the given type, creating a node of the
+/*!	Opens a BNode on the given type, creating a node of the
 	appropriate flavor if requested (and necessary).
+
 	All MIME types are converted to lowercase for use in the filesystem.
+
 	\param type The MIME type to open.
 	\param _node Node opened on the given MIME type.
 	\param _didCreate If not \c NULL, the variable the pointer refers to is
 	       set to \c true, if the node has been newly created, to \c false
 	       otherwise.
+
+	\return A status code.
 */
 status_t
 DatabaseLocation::OpenWritableType(const char* type, BNode& _node, bool create,
@@ -87,8 +92,8 @@ DatabaseLocation::OpenWritableType(const char* type, BNode& _node, bool create,
 
 	// See, if the type already exists.
 	int32 index;
-	status_t error = _OpenType(type, _node, index);
+	status_t result = _OpenType(type, _node, index);
-	if (error == B_OK) {
+	if (result == B_OK) {
 		if (index == 0)
 			return B_OK;
 		else if (!create)
@@ -100,35 +105,36 @@ DatabaseLocation::OpenWritableType(const char* type, BNode& _node, bool create,
 		if (nodeToClone.InitCheck() != B_OK)
 			return nodeToClone.InitCheck();
 
-		error = _CopyTypeNode(nodeToClone, type, _node);
+		result = _CopyTypeNode(nodeToClone, type, _node);
-		if (error != B_OK) {
+		if (result != B_OK) {
 			_node.Unset();
-			return error;
+			return result;
 		}
 
 		if (_didCreate != NULL)
 			*_didCreate = true;
-		return error;
+
+		return result;
 	} else if (!create)
 		return B_ENTRY_NOT_FOUND;
 
 	// type doesn't exist yet -- create the respective node
-	error = _CreateTypeNode(type, _node);
+	result = _CreateTypeNode(type, _node);
-	if (error != B_OK)
+	if (result != B_OK)
-		return error;
+		return result;
 
 	// write the type attribute
 	size_t toWrite = strlen(type) + 1;
 	ssize_t bytesWritten = _node.WriteAttr(kTypeAttr, B_STRING_TYPE, 0, type,
 		toWrite);
 	if (bytesWritten < 0)
-		error = bytesWritten;
+		result = bytesWritten;
 	else if ((size_t)bytesWritten != toWrite)
-		error = B_FILE_ERROR;
+		result = B_FILE_ERROR;
 
-	if (error != B_OK) {
+	if (result != B_OK) {
 		_node.Unset();
-		return error;
+		return result;
 	}
 
 	if (_didCreate != NULL)
@@ -137,17 +143,18 @@ DatabaseLocation::OpenWritableType(const char* type, BNode& _node, bool create,
 }
 
 
-/*! \brief Reads up to \c len bytes of the given data from the given attribute
+/*! Reads up to \c length bytes of the given data from the given attribute
 	for the given MIME type.
 
 	If no entry for the given type exists in the database, the function fails,
 	and the contents of \c data are undefined.
 
-	\param type The MIME type
+	\param type The MIME type.
-	\param attribute The attribute name
+	\param attribute The attribute name.
-	\param data Pointer to a memory buffer into which the data should be copied
+	\param data Pointer to a memory buffer into which the data should be copied.
-	\param length The maximum number of bytes to read
+	\param length The maximum number of bytes to read.
-	\param datatype The expected data type
+	\param datatype The expected data type.
+
 	\return If successful, the number of bytes read is returned, otherwise, an
 	        error code is returned.
 */
@@ -159,25 +166,27 @@ DatabaseLocation::ReadAttribute(const char* type, const char* attribute,
 		return B_BAD_VALUE;
 
 	BNode node;
-	status_t error = OpenType(type, node);
+	status_t result = OpenType(type, node);
-	if (error != B_OK)
+	if (result != B_OK)
-		return error;
+		return result;
 
 	return node.ReadAttr(attribute, datatype, 0, data, length);
 }
 
 
-/*! \brief Reads a flattened BMessage from the given attribute of the given
+/*!	Reads a flattened BMessage from the given attribute of the given
 	MIME type.
 
 	If no entry for the given type exists in the database, or if the data
 	stored in the attribute is not a flattened BMessage, the function fails
 	and the contents of \c msg are undefined.
 
-	\param type The MIME type
+	\param type The MIME type.
-	\param attribute The attribute name
+	\param attribute The attribute name.
 	\param data Reference to a pre-allocated BMessage into which the attribute
 	       data is unflattened.
+
+	\return A status code.
 */
 status_t
 DatabaseLocation::ReadMessageAttribute(const char* type, const char* attribute,
@@ -189,13 +198,13 @@ DatabaseLocation::ReadMessageAttribute(const char* type, const char* attribute,
 	BNode node;
 	attr_info info;
 
-	status_t error = OpenType(type, node);
+	status_t result = OpenType(type, node);
-	if (error != B_OK)
+	if (result != B_OK)
-		return error;
+		return result;
 
-	error = node.GetAttrInfo(attribute, &info);
+	result = node.GetAttrInfo(attribute, &info);
-	if (error != B_OK)
+	if (result != B_OK)
-		return error;
+		return result;
 
 	if (info.type != B_MESSAGE_TYPE)
 		return B_BAD_VALUE;
@@ -214,16 +223,17 @@ DatabaseLocation::ReadMessageAttribute(const char* type, const char* attribute,
 }
 
 
-/*! \brief Reads a BString from the given attribute of the given
+/*!	Reads a BString from the given attribute of the given MIME type.
-	MIME type.
 
 	If no entry for the given type exists in the database, the function fails
 	and the contents of \c str are undefined.
 
-	\param type The MIME type
+	\param type The MIME type.
-	\param attribute The attribute name
+	\param attribute The attribute name.
 	\param _string Reference to a pre-allocated BString into which the attribute
 	       data stored.
+
+	\return A status code.
 */
 status_t
 DatabaseLocation::ReadStringAttribute(const char* type, const char* attribute,
@@ -233,24 +243,26 @@ DatabaseLocation::ReadStringAttribute(const char* type, const char* attribute,
 		return B_BAD_VALUE;
 
 	BNode node;
-	status_t error = OpenType(type, node);
+	status_t result = OpenType(type, node);
-	if (error != B_OK)
+	if (result != B_OK)
-		return error;
+		return result;
 
 	return node.ReadAttrString(attribute, &_string);
 }
 
 
-/*! \brief Writes \c len bytes of the given data to the given attribute
+/*!	Writes \c len bytes of the given data to the given attribute
 	for the given MIME type.
 
 	If no entry for the given type exists in the database, it is created.
 
-	\param type The MIME type
+	\param type The MIME type.
-	\param attribute The attribute name
+	\param attribute The attribute name.
-	\param data Pointer to the data to write
+	\param data Pointer to the data to write.
-	\param length The number of bytes to write
+	\param length The number of bytes to write.
-	\param datatype The data type of the given data
+	\param datatype The data type of the given data.
+
+	\return A status code.
 */
 status_t
 DatabaseLocation::WriteAttribute(const char* type, const char* attribute,
@@ -260,9 +272,9 @@ DatabaseLocation::WriteAttribute(const char* type, const char* attribute,
 		return B_BAD_VALUE;
 
 	BNode node;
-	status_t error = OpenWritableType(type, node, true, _didCreate);
+	status_t result = OpenWritableType(type, node, true, _didCreate);
-	if (error != B_OK)
+	if (result != B_OK)
-		return error;
+		return result;
 
 	ssize_t bytesWritten = node.WriteAttr(attribute, datatype, 0, data, length);
 	if (bytesWritten < 0)
@@ -272,42 +284,44 @@ DatabaseLocation::WriteAttribute(const char* type, const char* attribute,
 }
 
 
-/*! \brief Flattens the given \c BMessage and writes it to the given attribute
+/*! Flattens the given \c BMessage and writes it to the given attribute
 	of the given MIME type.
 
 	If no entry for the given type exists in the database, it is created.
 
-	\param type The MIME type
+	\param type The MIME type.
-	\param attribute The attribute name
+	\param attribute The attribute name.
-	\param message The BMessage to flatten and write
+	\param message The BMessage to flatten and write.
+
+	\return A status code.
 */
 status_t
 DatabaseLocation::WriteMessageAttribute(const char* type, const char* attribute,
 	const BMessage& message, bool* _didCreate) const
 {
 	BMallocIO data;
-	status_t error = data.SetSize(message.FlattenedSize());
+	status_t result = data.SetSize(message.FlattenedSize());
-	if (error != B_OK)
+	if (result != B_OK)
-		return error;
+		return result;
 
 	ssize_t bytes;
-	error = message.Flatten(&data, &bytes);
+	result = message.Flatten(&data, &bytes);
-	if (error != B_OK)
+	if (result != B_OK)
-		return error;
+		return result;
 
 	return WriteAttribute(type, attribute, data.Buffer(), data.BufferLength(),
 		B_MESSAGE_TYPE, _didCreate);
 }
 
 
-//! Deletes the given attribute for the given type
+/*!	Deletes the given attribute for the given type
-/*!
+
 	\param type The mime type
 	\param attribute The attribute name
-	\return
+
-    - B_OK: success
+	\return A status code, \c B_OK on success or an error code on failure.
-    - B_ENTRY_NOT_FOUND: no such type or attribute
+	\retval B_OK Success.
-    - "error code": failure
+	\retval B_ENTRY_NOT_FOUND No such type or attribute.
 */
 status_t
 DatabaseLocation::DeleteAttribute(const char* type, const char* attribute) const
@@ -316,15 +330,15 @@ DatabaseLocation::DeleteAttribute(const char* type, const char* attribute) const
 		return B_BAD_VALUE;
 
 	BNode node;
-	status_t error = OpenWritableType(type, node, false);
+	status_t result = OpenWritableType(type, node, false);
-	if (error != B_OK)
+	if (result != B_OK)
-		return error;
+		return result;
 
 	return node.RemoveAttr(attribute);
 }
 
 
-/*! \brief Fetches the application hint for the given MIME type.
+/*! Fetches the application hint for the given MIME type.
 
 	The entry_ref pointed to by \c ref must be pre-allocated.
 
@@ -332,10 +346,9 @@ DatabaseLocation::DeleteAttribute(const char* type, const char* attribute) const
 	\param _ref Reference to a pre-allocated \c entry_ref struct into
 	       which the location of the hint application is copied.
 
-	\return
+	\return A status code, \c B_OK on success or an error code on failure.
-	- \c B_OK: Success
+	\retval B_OK Success.
-	- \c B_ENTRY_NOT_FOUND: No app hint exists for the given type
+	\retval B_ENTRY_NOT_FOUND No app hint exists for the given type
-	- "error code": Failure
 */
 status_t
 DatabaseLocation::GetAppHint(const char* type, entry_ref& _ref)
@@ -357,7 +370,7 @@ DatabaseLocation::GetAppHint(const char* type, entry_ref& _ref)
 }
 
 
-/*! \brief Fetches from the MIME database a BMessage describing the attributes
+/*!	Fetches from the MIME database a BMessage describing the attributes
 	typically associated with files of the given MIME type
 
 	The attribute information is returned in a pre-allocated BMessage pointed to
@@ -367,29 +380,31 @@ DatabaseLocation::GetAppHint(const char* type, entry_ref& _ref)
 
 	\param _info Reference to a pre-allocated BMessage into which information
 	       about the MIME type's associated file attributes is stored.
-	\return
+
-	- \c B_OK: Success
+	\return A status code, \c B_OK on success or an error code on failure.
-	- "error code": Failure
 */
 status_t
 DatabaseLocation::GetAttributesInfo(const char* type, BMessage& _info)
 {
-	status_t err = ReadMessageAttribute(type, kAttrInfoAttr, _info);
+	status_t result = ReadMessageAttribute(type, kAttrInfoAttr, _info);
-	if (err == B_ENTRY_NOT_FOUND) {
+
+	if (result == B_ENTRY_NOT_FOUND) {
 		// return an empty message
 		_info.MakeEmpty();
-		err = B_OK;
+		result = B_OK;
 	}
-	if (err == B_OK) {
+
+	if (result == B_OK) {
 		_info.what = 233;
 			// Don't know why, but that's what R5 does.
-		err = _info.AddString("type", type);
+		result = _info.AddString("type", type);
 	}
-	return err;
+
+	return result;
 }
 
 
-/*!	\brief Fetches the short description for the given MIME type.
+/*!	Fetches the short description for the given MIME type.
 
 	The string pointed to by \c description must be long enough to
 	hold the short description; a length of \c B_MIME_TYPE_LENGTH is
@@ -397,49 +412,50 @@ DatabaseLocation::GetAttributesInfo(const char* type, BMessage& _info)
 
 	\param type The MIME type of interest
 	\param description Pointer to a pre-allocated string into which the short
-		description is copied. If the function fails, the contents of the string
+	       description is copied. If the function fails, the contents of the
-		are undefined.
+	       string are undefined.
 
-	\return
+	\return A status code, \c B_OK on success or an error code on failure.
-	- \c B_OK: Success
+	\retval B_OK Success.
-	- \c 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.
-	- "error code": Failure
 */
 status_t
 DatabaseLocation::GetShortDescription(const char* type, char* description)
 {
-	ssize_t err = ReadAttribute(type, kShortDescriptionAttr, description,
+	ssize_t result = ReadAttribute(type, kShortDescriptionAttr, description,
 		B_MIME_TYPE_LENGTH, kShortDescriptionType);
-	return err >= 0 ? B_OK : err ;
+
+	return result >= 0 ? B_OK : result;
 }
 
 
-//!	Fetches the long description for the given MIME type.
+/*!	Fetches the long description for the given MIME type.
-/*!	The string pointed to by \c description must be long enough to
+
+	The string pointed to by \c description must be long enough to
 	hold the long description; a length of \c B_MIME_TYPE_LENGTH is
 	recommended.
 
 	\param type The MIME type of interest
 	\param description Pointer to a pre-allocated string into which the long
-		description is copied. If the function fails, the contents of the string
+	       description is copied. If the function fails, the contents of the
-		are undefined.
+	       string are undefined.
 
-	\return
+	\return A status code, \c B_OK on success or an error code on failure.
-	- \c B_OK: Success
+	\retval B_OK Success.
-	- \c B_ENTRY_NOT_FOUND: No long description exists for the given type
+	\retval B_ENTRY_NOT_FOUND No long description exists for the given type
-	- "error code": Failure
 */
 status_t
 DatabaseLocation::GetLongDescription(const char* type, char* description)
 {
-	ssize_t err = ReadAttribute(type, kLongDescriptionAttr, description,
+	ssize_t result = ReadAttribute(type, kLongDescriptionAttr, description,
 		B_MIME_TYPE_LENGTH, kLongDescriptionType);
-	return err >= 0 ? B_OK : err ;
+
+	return result >= 0 ? B_OK : result;
 }
 
 
-/*!	\brief Fetches a BMessage describing the MIME type's associated filename
+/*!	Fetches a BMessage describing the MIME type's associated filename
-	extensions
+	extensions.
 
 	The list of extensions is returned in a pre-allocated BMessage pointed to
 	by the \c extensions parameter (note that the any prior contents of the
@@ -448,28 +464,29 @@ DatabaseLocation::GetLongDescription(const char* type, char* description)
 
 	\param extensions Reference to a pre-allocated BMessage into which the MIME
 	       type's associated file extensions will be stored.
-	\return
+
-	- \c B_OK: Success
+	\return A status code, \c B_OK on success or an error code on failure.
-	- "error code": Failure
 */
 status_t
 DatabaseLocation::GetFileExtensions(const char* type, BMessage& _extensions)
 {
-	status_t err = ReadMessageAttribute(type, kFileExtensionsAttr, _extensions);
+	status_t result = ReadMessageAttribute(type, kFileExtensionsAttr, _extensions);
-	if (err == B_ENTRY_NOT_FOUND) {
+	if (result == B_ENTRY_NOT_FOUND) {
 		// return an empty message
 		_extensions.MakeEmpty();
-		err = B_OK;
+		result = B_OK;
 	}
-	if (err == B_OK) {
+
+	if (result == B_OK) {
 		_extensions.what = 234;	// Don't know why, but that's what R5 does.
-		err = _extensions.AddString("type", type);
+		result = _extensions.AddString("type", type);
 	}
-	return err;
+
+	return result;
 }
 
 
-/*!	\brief Fetches the icon of given size associated with the given MIME type
+/*!	Fetches the icon of given size associated with the given MIME type.
 
 	The bitmap pointed to by \c icon must be of the proper size (\c 32x32
 	for \c B_LARGE_ICON, \c 16x16 for \c B_MINI_ICON) and color depth
@@ -480,6 +497,8 @@ DatabaseLocation::GetFileExtensions(const char* type, BMessage& _extensions)
 	       color depth
 	\param size The size icon you're interested in (\c B_LARGE_ICON or
 	       \c B_MINI_ICON)
+
+	\return A status code.
 */
 status_t
 DatabaseLocation::GetIcon(const char* type, BBitmap& _icon, icon_size size)
@@ -488,11 +507,14 @@ DatabaseLocation::GetIcon(const char* type, BBitmap& _icon, icon_size size)
 }
 
 
-//! Fetches the vector icon associated with the given MIME type
+/*!	Fetches the vector icon associated with the given MIME type.
-/**	\param type The mime type
+
+	\param type The mime type
 	\param _data Reference via which the allocated icon data is returned. You
 	       need to free the buffer once you're done with it.
 	\param _size Reference via which the size of the icon data is returned.
+
+	\return A status code.
 */
 status_t
 DatabaseLocation::GetIcon(const char* type, uint8*& _data, size_t& _size)
@@ -501,7 +523,7 @@ DatabaseLocation::GetIcon(const char* type, uint8*& _data, size_t& _size)
 }
 
 
-/*! \brief Fetches the large or mini icon used by an application of this type
+/*!	Fetches the large or mini icon used by an application of this type
 	for files of the given type.
 
 	The type of the \c BMimeType object is not required to actually be a subtype
@@ -521,11 +543,10 @@ DatabaseLocation::GetIcon(const char* type, uint8*& _data, size_t& _size)
 	       colorspace into which the icon is copied.
 	\param icon_size Value that specifies which icon to return. Currently
 	       \c B_LARGE_ICON and \c B_MINI_ICON are supported.
-	\return
-	- \c B_OK: Success
-	- \c B_ENTRY_NOT_FOUND: No icon of the given size exists for the given type
-	- "error code": Failure
 
+	\return A status code, \c B_OK on success or an error code on failure.
+	\retval B_OK Success.
+	\retval B_ENTRY_NOT_FOUND No icon of the given size exists for the given type
 */
 status_t
 DatabaseLocation::GetIconForType(const char* type, const char* fileType,
@@ -536,16 +557,16 @@ DatabaseLocation::GetIconForType(const char* type, const char* fileType,
 
 	// open the node for the given type
 	BNode node;
-	ssize_t err = OpenType(type, node);
+	status_t result = OpenType(type, node);
-	if (err < B_OK)
+	if (result != B_OK)
-		return (status_t)err;
+		return result;
 
 	// construct our attribute name
 	BString vectorIconAttrName;
 	BString smallIconAttrName;
 	BString largeIconAttrName;
 
-	if (fileType) {
+	if (fileType != NULL) {
 		BString lowerCaseFileType(fileType);
 		lowerCaseFileType.ToLower();
 
@@ -560,88 +581,10 @@ DatabaseLocation::GetIconForType(const char* type, const char* fileType,
 
 	return BIconUtils::GetIcon(&node, vectorIconAttrName, smallIconAttrName,
 		largeIconAttrName, which, &_icon);
-
-//	ssize_t err = type && icon ? B_OK : B_BAD_VALUE;
-//
-//	// Figure out what kind of data we *should* find
-//	uint32 attrType = 0;
-//	ssize_t attrSize = 0;
-//	BRect bounds;
-//
-//	if (!err) {
-//		switch (which) {
-//			case B_MINI_ICON:
-//				bounds.Set(0, 0, 15, 15);
-//				attrType = kMiniIconType;
-//				attrSize = 16 * 16;
-//				break;
-//			case B_LARGE_ICON:
-//				bounds.Set(0, 0, 31, 31);
-//				attrType = kLargeIconType;
-//				attrSize = 32 * 32;
-//				break;
-//			default:
-//				err = B_BAD_VALUE;
-//				break;
-//		}
-//	}
-//	// Construct our attribute name
-//	std::string attr;
-//	if (fileType) {
-//		attr = (which == B_MINI_ICON
-//	              ? kMiniIconAttrPrefix
-//	                : kLargeIconAttrPrefix)
-//	                  + BPrivate::Storage::to_lower(fileType);
-//	} else {
-//		attr = (which == B_MINI_ICON) ? kMiniIconAttr : kLargeIconAttr;
-//	}
-//	// Check the icon and attribute to see if they match
-//	if (!err) {
-//		err = (icon->InitCheck() == B_OK
-//				&& icon->Bounds() == bounds) ? B_OK : B_BAD_VALUE;
-//	}
-//
-//	BNode node;
-//	if (!err)
-//		err = open_type(type, &node);
-//
-//	attr_info info;
-//	if (!err)
-//		err = node.GetAttrInfo(attr.c_str(), &info);
-//
-//	if (!err)
-//		err = (attrType == info.type && attrSize == info.size) ? B_OK : B_BAD_VALUE;
-//	// read the attribute
-//	if (!err) {
-//		bool otherColorSpace = (icon->ColorSpace() != B_CMAP8);
-//		char *buffer = NULL;
-//		if (otherColorSpace) {
-//			// other color space than stored in attribute
-//			buffer = new(std::nothrow) char[attrSize];
-//			if (!buffer)
-//				err = B_NO_MEMORY;
-//			if (!err)
-//				err = node.ReadAttr(attr.c_str(), attrType, 0, buffer, attrSize);
-//		} else {
-//			// same color space, just read direct
-//			err = node.ReadAttr(attr.c_str(), attrType, 0, icon->Bits(), attrSize);
-//		}
-//		if (err >= 0)
-//			err = (err == attrSize) ? (status_t)B_OK : (status_t)B_FILE_ERROR;
-//		if (otherColorSpace) {
-//			if (!err) {
-//				err = icon->ImportBits(buffer, attrSize, B_ANY_BYTES_PER_ROW,
-//									   0, B_CMAP8);
-//			}
-//			delete[] buffer;
-//		}
-//	}
-//
-//	return err;
 }
 
 
-/*! \brief Fetches the vector icon used by an application of this type for files
+/*!	Fetches the vector icon used by an application of this type for files
 	of the given type.
 
 	The type of the \c BMimeType object is not required to actually be a subtype
@@ -653,13 +596,14 @@ DatabaseLocation::GetIconForType(const char* type, const char* fileType,
 
 	\param type The MIME type
 	\param fileType Reference to a pre-allocated string containing the MIME type
-		whose custom icon you wish to fetch. If NULL, works just like GetIcon().
+	       whose custom icon you wish to fetch. If NULL, works just like
+	       GetIcon().
 	\param _data Reference via which the icon data is returned on success.
 	\param _size Reference via which the size of the icon data is returned.
-	\return
+
-	- \c B_OK: Success
+	\return A status code, \c B_OK on success or another code on failure.
-	- \c B_ENTRY_NOT_FOUND: No vector icon exists for the given type
+	\retval B_OK Success.
-	- "error code": Failure
+	\retval B_ENTRY_NOT_FOUND No vector icon existed for the given type.
 */
 status_t
 DatabaseLocation::GetIconForType(const char* type, const char* fileType,
@@ -670,54 +614,55 @@ DatabaseLocation::GetIconForType(const char* type, const char* fileType,
 
 	// open the node for the given type
 	BNode node;
-	ssize_t err = OpenType(type, node);
+	status_t result = OpenType(type, node);
-	if (err < B_OK)
+	if (result != B_OK)
-		return (status_t)err;
+		return result;
 
 	// construct our attribute name
 	BString iconAttrName;
 
-	if (fileType)
+	if (fileType != NULL)
 		iconAttrName << kIconAttrPrefix << BString(fileType).ToLower();
 	else
 		iconAttrName = kIconAttr;
 
 	// get info about attribute for that name
 	attr_info info;
-	if (!err)
+	if (result == B_OK)
-		err = node.GetAttrInfo(iconAttrName, &info);
+		result = node.GetAttrInfo(iconAttrName, &info);
 
 	// validate attribute type
-	if (!err)
+	if (result == B_OK)
-		err = (info.type == B_VECTOR_ICON_TYPE) ? B_OK : B_BAD_VALUE;
+		result = (info.type == B_VECTOR_ICON_TYPE) ? B_OK : B_BAD_VALUE;
 
 	// allocate a buffer and read the attribute data into it
-	if (!err) {
+	if (result == B_OK) {
 		uint8* buffer = new(std::nothrow) uint8[info.size];
-		if (!buffer)
+		if (buffer == NULL)
-			err = B_NO_MEMORY;
+			result = B_NO_MEMORY;
-		if (!err) {
+
-			err = node.ReadAttr(iconAttrName, B_VECTOR_ICON_TYPE, 0, buffer,
+		ssize_t bytesRead = -1;
+		if (result == B_OK) {
+			bytesRead = node.ReadAttr(iconAttrName, B_VECTOR_ICON_TYPE, 0, buffer,
 				info.size);
 		}
 
-		if (err >= 0)
+		if (bytesRead >= 0)
-			err = (err == info.size) ? (ssize_t)B_OK : (ssize_t)B_FILE_ERROR;
+			result = bytesRead == info.size ? B_OK : B_FILE_ERROR;
 
-		if (!err) {
+		if (result == B_OK) {
 			// success, set data pointer and size
 			_data = buffer;
 			_size = info.size;
-		} else {
+		} else
 			delete[] buffer;
 	}
-	}
 
-	return err;
+	return result;
 }
 
 
-/*!	\brief Fetches signature of the MIME type's preferred application for the
+/*!	Fetches signature of the MIME type's preferred application for the
 	given action.
 
 	The string pointed to by \c signature must be long enough to
@@ -732,10 +677,9 @@ DatabaseLocation::GetIconForType(const char* type, const char* fileType,
 	       the contents of the string are undefined.
 	\param verb \c The action of interest
 
-	\return
+	\return A status code, \c B_OK on success or another code on failure.
-	- \c B_OK: Success
+	\retval B_OK Success.
-	- \c B_ENTRY_NOT_FOUND: No such preferred application exists
+	\retval B_ENTRY_NOT_FOUND No such preferred application exists
-	- "error code": Failure
 */
 status_t
 DatabaseLocation::GetPreferredApp(const char* type, char* signature,
@@ -743,20 +687,21 @@ DatabaseLocation::GetPreferredApp(const char* type, char* signature,
 {
 	// Since B_OPEN is the currently the only app_verb, it is essentially
 	// ignored
-	ssize_t err = ReadAttribute(type, kPreferredAppAttr, signature,
+	ssize_t result = ReadAttribute(type, kPreferredAppAttr, signature,
 		B_MIME_TYPE_LENGTH, kPreferredAppType);
-	return err >= 0 ? B_OK : err ;
+
+	return result >= 0 ? B_OK : result;
 }
 
 
-/*! \brief Fetches the sniffer rule for the given MIME type.
+/*!	Fetches the sniffer rule for the given MIME type.
 	\param type The MIME type of interest
 	\param _result Pointer to a pre-allocated BString into which the type's
 	       sniffer rule is copied.
-	\return
+
-	- \c B_OK: Success
+	\return A status code, \c B_OK on success or another code on failure.
-	- \c B_ENTRY_NOT_FOUND: No such preferred application exists
+	\retval B_OK Success.
-	- "error code": Failure
+	\retval B_ENTRY_NOT_FOUND No such preferred application exists.
 */
 status_t
 DatabaseLocation::GetSnifferRule(const char* type, BString& _result)
@@ -768,17 +713,18 @@ DatabaseLocation::GetSnifferRule(const char* type, BString& _result)
 status_t
 DatabaseLocation::GetSupportedTypes(const char* type, BMessage& _types)
 {
-	status_t err = ReadMessageAttribute(type, kSupportedTypesAttr, _types);
+	status_t result = ReadMessageAttribute(type, kSupportedTypesAttr, _types);
-	if (err == B_ENTRY_NOT_FOUND) {
+	if (result == B_ENTRY_NOT_FOUND) {
 		// return an empty message
 		_types.MakeEmpty();
-		err = B_OK;
+		result = B_OK;
 	}
-	if (err == B_OK) {
+	if (result == B_OK) {
 		_types.what = 0;
-		err = _types.AddString("type", type);
+		result = _types.AddString("type", type);
 	}
-	return err;
+
+	return result;
 }
 
 
@@ -804,9 +750,9 @@ DatabaseLocation::_OpenType(const char* type, BNode& _node, int32& _index) const
 {
 	int32 count = fDirectories.CountStrings();
 	for (int32 i = 0; i < count; i++) {
-		status_t error = _node.SetTo(_TypeToFilename(type, i));
+		status_t result = _node.SetTo(_TypeToFilename(type, i));
 		attr_info attrInfo;
-		if (error == B_OK && _node.GetAttrInfo(kTypeAttr, &attrInfo) == B_OK) {
+		if (result == B_OK && _node.GetAttrInfo(kTypeAttr, &attrInfo) == B_OK) {
 			_index = i;
 			return B_OK;
 		}
@@ -829,25 +775,26 @@ DatabaseLocation::_CreateTypeNode(const char* type, BNode& _node) const
 
 	// open/create the directory for the supertype
 	BDirectory parent(WritableDirectory());
-	status_t error = parent.InitCheck();
+	status_t result = parent.InitCheck();
-	if (error != B_OK)
+	if (result != B_OK)
-		return error;
+		return result;
 
 	BDirectory superTypeDirectory;
 	if (BEntry(&parent, superTypeName).Exists())
-		error = superTypeDirectory.SetTo(&parent, superTypeName);
+		result = superTypeDirectory.SetTo(&parent, superTypeName);
 	else
-		error = parent.CreateDirectory(superTypeName, &superTypeDirectory);
+		result = parent.CreateDirectory(superTypeName, &superTypeDirectory);
-	if (error != B_OK)
+
-		return error;
+	if (result != B_OK)
+		return result;
 
 	// create the subtype
 	BFile subTypeFile;
 	if (slash != NULL) {
-		error = superTypeDirectory.CreateFile(BString(slash + 1).ToLower(),
+		result = superTypeDirectory.CreateFile(BString(slash + 1).ToLower(),
 			&subTypeFile);
-		if (error != B_OK)
+		if (result != B_OK)
-			return error;
+			return result;
 	}
 
 	// assign the result
@@ -863,9 +810,9 @@ status_t
 DatabaseLocation::_CopyTypeNode(BNode& source, const char* type, BNode& _target)
 	const
 {
-	status_t error = _CreateTypeNode(type, _target);
+	status_t result = _CreateTypeNode(type, _target);
-	if (error != B_OK)
+	if (result != B_OK)
-		return error;
+		return result;
 
 	// copy the attributes
 	MemoryDeleter bufferDeleter;
@@ -875,10 +822,10 @@ DatabaseLocation::_CopyTypeNode(BNode& source, const char* type, BNode& _target)
 	char attribute[B_ATTR_NAME_LENGTH];
 	while (source.GetNextAttrName(attribute) == B_OK) {
 		attr_info info;
-		error = source.GetAttrInfo(attribute, &info);
+		result = source.GetAttrInfo(attribute, &info);
-		if (error != B_OK) {
+		if (result != B_OK) {
 			syslog(LOG_ERR, "Failed to get info for attribute \"%s\" of MIME "
-				"type \"%s\": %s", attribute, type, strerror(error));
+				"type \"%s\": %s", attribute, type, strerror(result));
 			continue;
 		}