[haiku-commits] haiku: hrev43874 - src/kits/storage docs/user/storage

  • From: jscipione@xxxxxxxxx
  • To: haiku-commits@xxxxxxxxxxxxx
  • Date: Sun, 18 Mar 2012 05:25:12 +0100 (CET)

hrev43874 adds 1 changeset to branch 'master'
old head: 65bce31ef8d48ff69c73970e5afdc5c23d47ca3c
new head: 12c10314f945b805b99210abc9aebb07ecede4b0

----------------------------------------------------------------------------

12c1031: Remove MimeType docs from MimeType.cpp and cleanup style issues in 
that file. Create a MimeType.dox file and add the docs there.

                                     [ John Scipione <jscipione@xxxxxxxxx> ]

----------------------------------------------------------------------------

Revision:    hrev43874
Commit:      12c10314f945b805b99210abc9aebb07ecede4b0
URL:         http://cgit.haiku-os.org/haiku/commit/?id=12c1031
Author:      John Scipione <jscipione@xxxxxxxxx>
Date:        Sun Mar 18 04:09:53 2012 UTC

----------------------------------------------------------------------------

2 files changed, 1475 insertions(+), 1028 deletions(-)
docs/user/storage/MimeType.dox | 1206 +++++++++++++++++++++++++++++++++
src/kits/storage/MimeType.cpp  | 1297 ++++++++----------------------------

----------------------------------------------------------------------------

diff --git a/docs/user/storage/MimeType.dox b/docs/user/storage/MimeType.dox
new file mode 100644
index 0000000..7413045
--- /dev/null
+++ b/docs/user/storage/MimeType.dox
@@ -0,0 +1,1206 @@
+/*
+ * Copyright 2011 Haiku, Inc. All rights reserved.
+ * Distributed under the terms of the MIT License.
+ *
+ * Authors:
+ *             Tyler Dauwalder
+ *             Ingo Weinhold, bonefish@xxxxxxxxxxxx
+ *             Axel Dörfler, axeld@xxxxxxxxxxxxxxxx
+ *             John Scipione, jscipione@xxxxxxxxx
+ * Corresponds to:
+ *             headers/os/storage/MimeType.h  hrev43528
+ *             src/kits/storage/MimeType.cpp  hrev43528
+ */
+
+
+/*!
+       \file MimeType.h
+       \brief Provides the BMimeType class.
+*/
+
+
+/*!
+       \class BMimeType
+       \ingroup storage
+       \ingroup libbe
+       \brief A class that represents a MIME (Multipurpose 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 
+*/
+
+
+/*!
+       \fn BMimeType::BMimeType()
+       \brief Creates an uninitialized BMimeType object.
+*/
+
+
+/*!
+       \fn BMimeType::BMimeType(const char *mimeType)
+       \brief Creates a BMimeType object and initializes it to the supplied
+               MIME type.
+
+       The supplied string must specify a valid MIME type or supertype.
+
+       \param mimeType The MIME string.
+
+       \sa SetTo() for further information.
+*/
+
+
+/*!
+       \fn BMimeType::~BMimeType()
+       \brief Frees all resources associated with this object.
+*/
+
+
+/*!
+       \fn status_t BMimeType::SetTo(const char *mimeType)
+       \brief Initializes this object to the supplied MIME type.
+
+       The supplied string must specify a valid MIME type or supertype.
+       Valid MIME types are given by the following grammar:
+
+       MIMEType        ::= Supertype "/" [ Subtype ]
+       Supertype       ::= "application" | "audio" | "image" | "message"
+                                       | "multipart" | "text" | "video"
+       Subtype         ::= MIMEChar MIMEChar*
+       MIMEChar        ::= any character except white spaces, CTLs and '/', 
'<', '>',
+                                       '@',, ',', ';', ':', '"', '(', ')', 
'[', ']', '?', '=', '\'
+                                       (Note: RFC1341 also forbits '.', but it 
is allowed here.)
+
+       Currently the supertype is not restricted to one of the seven types 
given,
+       but can be an arbitrary string (obeying the same rule as the subtype).
+       Nevertheless it is a very bad idea to use another supertype.
+       The supplied MIME string is copied; the caller retains the ownership.
+
+       \param mimeType The MIME string.
+
+       \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_MEMORY Insufficient memory to copy the MIME string.
+*/
+
+
+/*!
+       \fn void BMimeType::Unset()
+       \brief Returns the object to an uninitialized state.
+*/
+
+
+/*!
+       \fn status_t BMimeType::InitCheck() const
+       \brief Returns the result of the most recent constructor or SetTo() 
call.
+
+       \returns \c B_OK If the object is properly initialized, a specific
+               error code otherwise.
+*/
+
+
+/*!
+       \fn const char* BMimeType::Type() const
+       \brief Returns the MIME string represented by this object.
+
+       \return The MIME string, if the object is properly initialized, \c NULL
+                       otherwise.
+*/
+
+
+/*!
+       \fn bool BMimeType::IsValid() const
+       \brief Returns whether the object represents a valid MIME type.
+
+       \return \c true, if the object is properly initialized, \c false
+                       otherwise.
+
+       \sa SetTo() for further information.
+*/
+
+
+/*!
+       \fn bool BMimeType::IsSupertypeOnly() const
+       \brief Returns whether this objects represents a supertype.
+
+       \return \c true, if the object is properly initialized and represents a
+                       supertype, \c false otherwise.
+*/
+
+
+/*!
+       \fn bool BMimeType::IsInstalled() const
+       \brief Returns whether or not this type is currently installed in the
+                  MIME database.
+
+       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
+                        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.
+*/
+
+
+/*!
+       \fn status_t BMimeType::GetSupertype(BMimeType *superType) const
+       \brief Gets the supertype of the MIME type represented by this object.
+
+       The supplied object is initialized to this object's 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
+                  initialized to this object's 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.
+*/
+
+
+/*!
+       \fn bool BMimeType::operator==(const BMimeType &type) const
+       \brief Returns whether this and the supplied MIME type are equal.
+
+       Two BMimeType objects are said to be equal if they represent the same
+       MIME string, ignoring case, or if both are not initialized.
+
+       \warning In BeOS R5 two uninitialized BMimeType objects were not
+               considered to be equal, in Haiku they are.
+
+       \param type The BMimeType to be compared with.
+
+       \return \c true, if the objects are equal, \c false otherwise.
+*/
+
+
+/*!
+       \fn bool BMimeType::operator==(const char *type) const
+       \brief Returns whether this and the supplied MIME type are equal.
+
+       A BMimeType objects equals a MIME string, if its MIME string equals the
+       latter one, ignoring case, or if it is uninitialized and the MIME string
+       is \c NULL.
+
+       \warning In BeOS R5 an uninitialized BMimeType object was not
+               considered to be equal to \c NULL, in Haiku it is.
+
+       \param type The MIME string to be compared with.
+
+       \return \c true, if the MIME types are equal, \c false otherwise.
+*/
+
+
+/*!
+       \fn bool BMimeType::Contains(const BMimeType *type) const
+       \brief Returns whether this MIME type is a supertype of or equals the
+       supplied one.
+
+       \param type The MIME type.
+
+       \returns \c true, if this MIME type is a supertype of or equals the
+                       supplied one, \c false otherwise.
+*/
+
+
+/*!
+       \fn status_t BMimeType::Install()
+       \brief Adds the MIME type to the MIME database.
+
+       To check if the MIME type is already installed, call \c IsInstalled().
+       To remove the MIME type from the database, call \c Delete().
+       
+       \note The R5 implementation returns random values if the type is already
+       installed, so be sure to check \c IsInstalled() first.
+       
+       \returns \c B_OK on success or another error code on failure.
+*/
+
+
+/*!
+       \fn status_t BMimeType::Delete()
+       \brief Removes the MIME type from the MIME database.
+
+       To check if the MIME type is already installed, call \c IsInstalled().
+       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
+       database.
+       
+       \returns \c B_OK on success or another error code on failure.
+*/
+
+
+/*!
+       \fn status_t BMimeType::GetIcon(BBitmap *icon, icon_size size) const
+       \brief Fetches the large or mini icon associated with the MIME type.
+
+       The icon is copied into the \c BBitmap pointed to by \c icon. The bitmap
+       must be the proper size: \c 32x32 for the large icon, \c 16x16 for the 
mini
+       icon. Additionally, the bitmap must be in the \c B_CMAP8 color space
+       (8-bit color).
+
+       \param icon Pointer to a pre-allocated \c BBitmap of proper size and
+                               colorspace into which the icon is copied.
+       \param size Value that specifies which icon to return.
+                               Currently \c B_LARGE_ICON and \c B_MINI_ICON 
are supported.
+
+       \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 type.
+*/
+
+
+/*!
+       \fn status_t BMimeType::GetIcon(uint8** data, size_t* size) const
+       \brief Fetches the vector icon associated with the MIME type
+               The icon data is returned in \c data.
+
+       \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.
+
+       \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
+               type
+*/
+
+
+/*!
+       \fn status_t BMimeType::GetPreferredApp(char *signature, app_verb verb)
+               const
+       \brief Fetches the signature of the MIME type's preferred application 
from
+               the MIME database.
+
+       The preferred app is the application that's used to access a file when,
+       for example, the user double-clicks the file in a Tracker window. Unless
+       the file identifies in its attributes a "custom" preferred app, Tracker
+       will ask the file type database for the preferred app
+       that's associated with the file's type.
+
+       The string pointed to by \c signature must be long enough to
+       hold the preferred applications signature; a length of
+       \c B_MIME_TYPE_LENGTH is recommended.
+       
+       \param signature Pointer to a pre-allocated string into which the
+               signature of the preferred app is copied. If the function fails,
+               the contents of the string are undefined.
+       \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.
+*/
+
+
+/*!
+       \fn status_t BMimeType::GetAttrInfo(BMessage *info) const
+       \brief 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 by the \c info parameter (note that the any prior contents of the
+       message will be destroyed). If the method succeeds, the format of the
+       BMessage pointed to by \c info will be the following:
+
+       <table>
+               <tr>
+                       <td><b>field name</b></td>
+                       <td><b>type</b></td>
+                       <td><b>element[0..n]</b></td>
+               </tr>
+               <tr>
+                       <td> "attr:name"</td>
+                       <td> \c B_STRING_TYPE </td>
+                       <td> The name of each attribute </td>
+               </tr>
+               <tr>
+                       <td> "attr:public_name"</td>
+                       <td> \c B_STRING_TYPE </td>
+                       <td> The human-readable name of each attribute </td>
+               </tr>
+               <tr>
+                       <td> "attr:type"</td>
+                       <td> \c B_INT32_TYPE </td>
+                       <td> The type code for each attribute </td>
+               </tr>
+               <tr>
+                       <td> "attr:viewable"</td>
+                       <td> \c B_BOOL_TYPE </td>
+                       <td> For each attribute: \c true if the attribute is 
public,
+                               \c false if it's private </td>
+               </tr>
+               <tr>
+                       <td> "attr:editable"</td>
+                       <td> \c B_BOOL_TYPE </td>
+                       <td> For each attribute: \c true if the attribute 
should be user
+                               editable, \c false if not </td>
+               </tr>
+       </table>
+       
+       The \c BMessage::what value is set to decimal \c 233, but is otherwise
+       meaningless.
+
+       \param info Pointer to a pre-allocated BMessage into which information 
about
+                   the MIME type's associated file attributes is stored.
+
+       \returns \c B_OK on success or another error code on failure.
+*/
+
+
+/*!
+       \fn status_tBMimeType::GetFileExtensions(BMessage *extensions) const
+       \brief Fetches the MIME type's associated filename extensions from the
+               MIME database.
+
+       The MIME database associates a list of filename extensions (a character
+       string following the rightmost dot, \c ".", character in the filename)
+       with each type. These extensions can then be used to help determine the
+       type of any untyped files that may be encountered.
+
+       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 message will be destroyed). If the method succeeds, the format of
+       the BMessage pointed to by \c extensions will be the following:
+
+               - The message's \c "extensions" field will contain an indexed 
array
+                       of strings, one for each extension. The extensions are 
given
+                       without the preceding \c "." character by convention. 
+               - The message's \c "type" field will be a string containing the
+                       MIME type whose associated file extensions you are 
fetching.
+               - The \c what member of the BMessage will be set to \c 234, but
+                       is otherwise irrelevant.
+
+       Note that any other fields present in the BMessage passed to the most
+       recent \c SetFileExtensions() call will also be returned.
+         
+       \param extensions Pointer to a pre-allocated BMessage into which the
+                         MIME type's associated file extensions will be stored.
+
+       \returns \c B_OK on success or another error code on failure.
+*/
+
+
+/*!
+       \fn status_t BMimeType::GetShortDescription(char *description) const
+       \brief Fetches the MIME type's short description from the MIME database.
+
+       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
+       recommended.
+       
+       \param description Pointer to a pre-allocated string into which the long
+               description is copied. If the function fails, the contents of 
the
+               string are undefined.
+
+       \returns A status code.
+       \retval B_OK Success
+       \retval B_ENTRY_NOT_FOUND No short description exists for the given type
+*/
+
+
+/*!
+       \fn status_t BMimeType::GetLongDescription(char *description) const
+       \brief Fetches the MIME type's long description from the MIME database.
+
+       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 description Pointer to a pre-allocated string into which the
+               long description is copied. If the function fails, the contents
+               of the string are undefined.
+
+       \returns A status code.
+       \retval B_OK Success
+       \retval B_ENTRY_NOT_FOUND No long description exists for the given type.
+*/
+
+
+/*!
+       \fn status_t BMimeType::GetSupportingApps(BMessage *signatures) const
+       \brief Fetches a \c BMessage containing a list of MIME signatures of
+               applications that are able to handle files of this MIME type.
+
+       If successful, the BMessage containing the MIME signatures will be of
+       the following format:
+
+       <table>
+               <tr>
+                       <td><b>field name</b></td>
+                       <td><b>type</b></td>
+                       <td><b>contains</b></td>
+               </tr>
+               <tr>
+                       <td> "applications"</td>
+                       <td> \c B_STRING_TYPE[] </td>
+                       <td>
+                               An array of MIME signatures. The first <i> n 
</i> signatures
+                               (where <i> n </i> is the value in the \c 
"be:sub" field of the
+                               message) are able to handle the full type 
(supertype
+                               <i> and </i> subtype). The remaining signatures 
are of
+                               applications that handle the supertype only.
+                       </td>
+               </tr>
+               <tr>
+                       <td> "be:sub"</td>
+                       <td> \c B_INT32_TYPE </td>
+                       <td>
+                               The number of applications in the \c 
"applications" array that
+                               can handle the object's full MIME type. These 
applications are
+                               listed first in the array. This field is 
omitted if the object
+                               represents a supertype only.
+                       </td>
+               </tr>
+               <tr>
+                       <td> "be:super"</td>
+                       <td> \c B_INT32_TYPE </td>
+                       <td>
+                               The number of applications in the 
"applications" array that can
+                               handle the object's supertype (not counting 
those that can
+                               handle the full type).
+                               These applications are listed after the 
full-MIME-type
+                               supporters. By definition, the \c 
GetWildcardApps() function
+                               never returns supertype-only apps.
+                       </td>
+               </tr>
+       </table>
+
+       The \c BMessage::what value is meaningless and should be ignored.
+
+       \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.
+*/
+
+
+/*!
+       \fn status_t BMimeType::SetIcon(const BBitmap *icon, icon_size which)
+       \brief Sets the large or mini icon for the MIME type.
+
+       The icon is copied from the \c BBitmap pointed to by \c icon. The bitmap
+       must be the proper size: \c 32x32 for the large icon, \c 16x16 for the 
mini
+       icon. Additionally, the bitmap must be in the \c B_CMAP8 color space 
(8-bit
+       color).
+
+       If you want to erase the current icon, pass \c NULL as the \c icon 
argument.
+
+       \param icon Pointer to a pre-allocated \c BBitmap of proper size and
+               colorspace containing the new icon, or \c NULL to clear the 
current
+               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.
+*/
+
+
+/*!
+       \fn status_t BMimeType::SetIcon(const uint8* data, size_t size)
+       \brief Sets the vector icon for the MIME type
+
+       The icon is copied from the provided \a data which must contain
+       \a size bytes.
+
+       If you want to erase the current icon, pass \c NULL as the \a data 
argument.
+
+       \param data Pointer to a buffer containing the new icon, or \c NULL to 
clear
+                               the current icon.
+       \param size Size of the provided buffer.
+
+       \returns \c B_OK on success or another error code on failure.
+*/
+
+
+// 
+/*!
+       \fn status_t BMimeType::SetP0referredApp(const char *signature,
+               app_verb verb)
+       \brief Sets the preferred application for the MIME type.
+
+       The preferred app is the application that's used to access a file when,
+       for example, the user double-clicks the file in a Tracker window. Unless
+       the file identifies in its attributes a "custom" preferred app, Tracker
+       will ask the file type database for the preferred app that's associated
+       with the file's type.
+
+       The string pointed to by \c signature must be of length less than
+       \c B_MIME_TYPE_LENGTH characters.
+
+       \note If the MIME type is not installed, it will first be installed,
+       and then the preferred app will be set.
+
+       \param signature Pointer to a pre-allocated string containing the
+               signature of the new preferred app.
+       \param verb \c app_verb value that specifies the type of access for
+               which you are setting the preferred app. Currently, the only
+               supported app verb is \c B_OPEN.
+
+       \returns \c B_OK on success or another error code on failure.*/
+*/
+
+
+/*!
+       \fn status_t BMimeType::SetAttrInfo(const BMessage *info)
+       \brief Sets the description of the attributes typically associated
+               with files of the given MIME type
+
+       The attribute information is technically arbitrary, but the expected
+       format of the BMessage pointed to by the \c info parameter is as 
follows:
+
+       <table>
+               <tr>
+                       <td><b>field name</b></td>
+                       <td><b>type</b></td>
+                       <td><b>element[0..n]</b></td>
+               </tr>
+               <tr>
+                       <td> "attr:name"</td>
+                       <td> \c B_STRING_TYPE </td>
+                       <td> The name of each attribute </td>
+               </tr>
+               <tr>
+                       <td> "attr:public_name"</td>
+                       <td> \c B_STRING_TYPE </td>
+                       <td> The human-readable name of each attribute </td>
+               </tr>
+               <tr>
+                       <td> "attr:type"</td>
+                       <td> \c B_INT32_TYPE </td>
+                       <td> The type code for each attribute </td>
+               </tr>
+               <tr>
+                       <td> "attr:viewable"</td>
+                       <td> \c B_BOOL_TYPE </td>
+                       <td> For each attribute: \c true if the attribute is 
public,
+                               \c false if it's private </td>
+               </tr>
+               <tr>
+                       <td> "attr:editable"</td>
+                       <td> \c B_BOOL_TYPE </td>
+                       <td> For each attribute: \c true if the attribute 
should be
+                               user editable, \c false if not </td>
+               </tr>
+       </table>
+       
+       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
+               with the MIME type.
+
+       \returns \c B_OK on success or another error code on failure.
+*/
+
+
+/*!
+       \fn status_t BMimeType::SetFileExtensions(const BMessage *extensions)
+       \brief Sets the list of filename extensions associated with the MIME 
type.
+
+       The MIME database associates a list of filename extensions (a character
+       string following the rightmost dot, \c ".", character in the filename)
+       with each type. These extensions can then be used to help determine the
+       type of any untyped files that may be   encountered.
+
+       The list of extensions is given in a pre-allocated BMessage pointed to 
by
+       the \c extensions parameter. The format of the message should be as 
follows:
+               - The message's \c "extensions" field should contain an indexed 
array of
+                       strings, one for each extension. The extensions are to 
be given
+                       without the preceding \c "." character (i.e. \c "html" 
or \c "mp3",
+                       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
+       and returned by calls to \c GetFileExtensions(); however, this may 
change in
+       the future, so it is recommended that you not rely on this behaviour, 
and
+       that no other fields be present. Also, note that no checking is 
performed to
+       verify the \c BMessage is properly 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
+       retrieve the existing set, add the new ones, and then call
+       \c SetFileExtensions(). 
+         
+       \param extensions Pointer to a pre-allocated, properly formatted 
BMessage
+               containing the new list of file extensions to associate with 
this MIME
+               type.
+
+       \returns \c B_OK on success or another error code on failure.
+*/
+
+
+/*!
+       \fn status_t BMimeType::SetShortDescription(const char *description)
+       \brief Sets the short description field for the MIME type.
+
+       The string pointed to by \c description must be of length less than
+       \c B_MIME_TYPE_LENGTH characters.
+
+       \note If the MIME type is not installed, it will first be installed,
+       and then the short description will be set.
+
+       \param description Pointer to a pre-allocated string containing the
+               new short description.
+
+       \returns \c B_OK on success or another error code on failure.
+*/
+
+
+/*!
+       \fn status_t BMimeType::SetLongDescription(const char *description)
+       \brief Sets the long description field for the MIME type.
+
+       The string pointed to by \c description must be of length less than
+       \c B_MIME_TYPE_LENGTH characters.
+
+       \note If the MIME type is not installed, it will first be installed,
+       and then the long description will be set.
+
+       \param description Pointer to a pre-allocated string containing the new
+               long description
+
+       \returns \c B_OK on success or another error code on failure.
+*/
+
+
+/*!
+       \fn status_t BMimeType::GetInstalledSupertypes(BMessage *supertypes)
+       \brief Fetches a BMessage listing all the MIME 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.
+
+       \returns \c B_OK on success or another error code on failure.
+*/
+
+
+/*!
+       \fn status_t BMimeType::GetInstalledTypes(BMessage *types)
+       \brief Fetches a BMessage listing all the MIME types currently installed
+       in the MIME database.
+
+       The types are copied into the \c "types" field of the passed-in \c 
BMessage.
+       The \c BMessage must be pre-allocated.
+
+       \param types Pointer to a pre-allocated \c BMessage into which the 
+                    MIME types will be copied.
+
+       \returns \c B_OK on success or another error code on failure.
+*/
+
+
+/*!
+       \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.
+
+       The types are copied into the \c "types" field of the passed-in \c 
BMessage.
+       The \c BMessage must be pre-allocated.
+
+       \param supertype Pointer to a string containing the MIME 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.
+*/
+
+
+/*!
+       \fn status_t BMimeType::GetWildcardApps(BMessage *wild_ones)
+       \brief Fetches a \c BMessage containing a list of MIME signatures of
+               applications that are able to handle files of any type.
+
+       This function is the same as calling \c GetSupportingApps() on a
+       \c BMimeType object initialized to a MIME type of]
+       \c "application/octet-stream".
+
+       \param wild_ones Pointer to a pre-allocated BMessage into which
+                                        signatures of applications supporting 
files of any type
+                                        are copied.
+
+       \returns \c B_OK on success or another error code on failure.
+
+       \sa GetSupportingApps() for details on the format of the data returned 
in
+               the \c BMessage pointed to by \c wild_ones.
+*/
+
+
+/*!
+       \fn bool BMimeType::IsValid(const char *string)
+       \brief Returns whether the given string represents a valid MIME type.
+
+       \param string The MIME type string.
+
+       \return \c true, if the given string represents a valid MIME type.
+
+       \sa SetTo() for further information.
+*/
+
+
+
+/*!
+       \fn status_t BMimeType::GetAppHint(entry_ref *ref) const
+       \brief Fetches an \c entry_ref that serves as a hint as to where the 
MIME
+               type's preferred application might live
+
+       The app hint is a path that identifies the executable that should be 
used
+       when launching an application that has this signature. For example, when
+       Tracker needs to launch an app of type \c "application/YourAppHere",
+       it asks the database for the application hint. This hint is converted 
to an
+       \c entry_ref before it is passed to the caller. Of course, the path may 
not
+       point to an application, or it might point to an application
+       with the wrong signature (and so on); that's why this is merely a hint.
+
+       The \c entry_ref pointed to by \c ref must be pre-allocated.
+
+       \param ref Pointer to a pre-allocated \c entry_ref into which the 
location
+                          of the app hint is copied. If the function fails, 
the contents of
+                          the \c entry_ref are undefined.
+
+       \return
+       - \c B_OK: Success
+       - \c B_ENTRY_NOT_FOUND: No app hint exists for the given type
+       - other error code: Failure
+*/
+
+
+/*!
+       \fn status_t BMimeType::SetAppHint(const entry_ref *ref)
+       \brief Sets the app hint field for the MIME type
+
+       The app hint is a path that identifies the executable that should be 
used
+       when launching an application that has this signature. For example, when
+       Tracker needs to launch an app of type \c "application/YourAppHere",
+       it asks the database for the application hint. This hint is converted 
to an
+       \c entry_ref before it is passed to the caller. Of course, the path may 
not
+       point to an application, or it might point to an application with the 
wrong
+       signature (and so on); that's why this is merely a hint.
+
+       The \c entry_ref pointed to by \c ref must be pre-allocated. It must be 
a
+       valid \c entry_ref (i.e. <code>entry_ref(-1, -1, "some_file")</code> 
will
+       trigger an error), but it need not point to an existing file, nor need
+       it actually point to an application. That's not to say that it 
shouldn't;
+       such an \c entry_ref would render the app hint useless.
+
+       \param ref Pointer to a pre-allocated \c entry_ref containting the 
location
+               of the new app hint
+
+       \returns \c B_OK on success or another error code on failure.
+*/
+
+
+/*!
+       \fn status_t BMimeType::GetIconForType(const char *type, BBitmap *icon,
+               icon_size which) const
+       \brief Fetches the large or mini icon used by an application of this 
type
+               for files of the given type.
+       
+       This can be confusing, so here's how this function is intended to be 
used:
+               - The actual \c BMimeType object should be set to the MIME 
signature
+                       of an application for whom you want to look up custom 
icons for
+                       custom MIME types.
+               - The \c type parameter specifies the file type whose custom 
icon you
+                       are fetching.
+
+       The type of the \c BMimeType object is not required to actually be a
+       subtype of \c "application/"; that is the intended use however, and 
calling
+       \c GetIconForType() on a non-application type will likely return
+       \c B_ENTRY_NOT_FOUND.
+
+       The icon is copied into the \c BBitmap pointed to by \c icon. The bitmap
+       must be the proper size: \c 32x32 for the large icon, \c 16x16 for the
+       mini icon. Additionally, the bitmap must be in the \c B_CMAP8 color 
space
+       (8-bit color).
+
+       \param type Pointer to a pre-allocated string containing the MIME type 
whose
+                   custom icon you wish to fetch.
+       \param icon Pointer to a pre-allocated \c BBitmap of proper size and
+                               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.
+
+       \returns A status code.
+       \retval B_OK Success
+       \retval B_ENTRY_NOT_FOUND No icon of the given size exists for the
+                       given type
+*/
+
+
+/*!
+       \fn status_t BMimeType::GetIconForType(const char *type,
+               uint8** _data, size_t* _size) const
+       \brief Fetches the vector icon used by an application of this type for
+               files of the given type.
+
+       The icon data is returned in \c data.
+       See the other GetIconForType() for more information.
+
+       \param type Pointer to a pre-allocated string containing the MIME type 
whose
+                               custom icon you wish to fetch.
+       \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.
+
+       \returns A status code.
+       \retval B_OK Success
+       \retval B_ENTRY_NOT_FOUND No icon of the given size exists for the
+               given type.
+*/
+
+
+/*!
+       \fn status_t BMimeType::SetIconForType(const char *type,
+               const BBitmap *icon, icon_size which)
+       \brief Sets the large or mini icon used by an application of this type
+               for files of the given type.
+
+       This can be confusing, so here's how this function is intended to be 
used:
+       - The actual \c BMimeType object should be set to the MIME signature of 
an
+         application to whom you want to assign custom icons for custom MIME 
types.
+       - The \c type parameter specifies the file type whose custom icon you 
are
+         setting.
+
+       The type of the \c BMimeType object is not required to actually be a 
subtype
+       of \c "application/"; that is the intended use however, and
+       application-specific icons are not expected to be present for
+       non-application types.
+       
+       The icon is copied from the \c BBitmap pointed to by \c icon. The bitmap
+       must be the proper size: \c 32x32 for the large icon, \c 16x16 for the 
mini
+       icon.
+
+       If you want to erase the current icon, pass \c NULL as the \c icon 
argument.
+
+       \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
+                               current 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.
+*/
+
+
+/*!
+       \fn status_t
+       BMimeType::SetIconForType(const char* type, const uint8* data,
+               size_t dataSize)
+       \brief Sets the large or mini icon used by an application of this type 
for
+       files of the given type.
+
+       This can be confusing, so here's how this function is intended to be 
used:
+       - The actual \c BMimeType object should be set to the MIME signature of 
an
+         application to whom you want to assign custom icons for custom MIME 
types.
+       - The \c type parameter specifies the file type whose custom icon you 
are
+         setting.
+       
+       The type of the \c BMimeType object is not required to actually be a 
subtype
+       of \c "application/"; that is the intended use however, and
+       application-specific icons are not expected to be present for
+       non-application types.
+               
+       The icon is copied from the \c BBitmap pointed to by \c icon. The bitmap
+       must be the proper size: \c 32x32 for the large icon, \c 16x16 for the 
mini
+       icon.
+
+       If you want to erase the current icon, pass \c NULL as the \c icon 
argument.
+
+       \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
+                               current icon.
+       \param icon_size 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.
+*/
+
+
+/*!
+       \fn status_t BMimeType::GetSnifferRule(BString *result) const
+       \brief Retrieves the MIME type's sniffer rule.
+
+       \param result Pointer to a pre-allocated BString into which the value is
+                  copied.
+
+       \returns A status code.
+       \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.
+*/
+
+
+/*!
+       \fn status_t BMimeType::SetSnifferRule(const char *rule)
+       \brief Sets the MIME type's sniffer rule.
+
+       If the supplied \a rule is \c NULL, the MIME type's sniffer rule is
+       unset.
+
+       SetSnifferRule() does also return \c B_OK, if the type is not installed,
+       but the call will have no effect in this case.
+
+       \param rule The rule string, may be \c NULL.
+
+       \returns A status code.
+       \retval B_OK Everything went fine.
+       \retval B_BAD_VALUE Uninitialized BMimeType.
+       \retval B_BAD_MIME_SNIFFER_RULE The supplied sniffer rule is invalid.
+
+       \sa CheckSnifferRule().
+*/
+
+
+/*!
+       \fn status_t BMimeType::CheckSnifferRule(const char *rule,
+               BString *parseError)
+       \brief Checks whether a MIME sniffer rule is valid or not.
+
+       A MIME sniffer rule is valid, if it is well-formed with respect to the
+       following grammar and fulfills some further conditions listed 
thereafter:
+
+\verbatim
+       Rule                    ::= LWS Priority LWS ExprList LWS
+       ExprList                ::= Expression (LWS Expression)*
+       Expression              ::= "(" LWS (PatternList | RPatternList) LWS ")"
+                                               | Range LWS "(" LWS PatternList 
LWS ")"
+       RPatternList    ::= RPattern (LWS "|" LWS RPattern)*
+       PatternList             ::= Pattern (LWS "|" LWS Pattern)*
+       RPattern                ::= Range LWS Pattern
+       Pattern                 ::= PString [ LWS "&" LWS Mask ]
+       Range                   ::=     "[" LWS SDecimal [LWS ":" LWS SDecimal] 
LWS "]"
+
+       Priority                ::= Float
+       Mask                    ::= PString
+       PString                 ::= HexString | QuotedString | Octal 
[UnquotedString]
+                                               EscapedChar [UnquotedString]
+       HexString               ::= "0x" HexPair HexPair*
+       HexPair                 ::= HexChar HexChar
+       QuotedString    ::= '"' QChar QChar* '"' | "'" QChar QChar* "'"
+       Octal                   ::= "\" OctChar [OctChar [OctChar]]
+       SDecimal                ::= ["+" | "-"] Decimal
+       Decimal                 ::= DecChar DecChar*
+       Float                   ::= Fixed [("E" | "e") Decimal]
+       Fixed                   ::= SDecimal ["." [Decimal]] | [SDecimal] "." 
Decimal
+       UnquotedString  ::= UChar UChar*
+       LWS                             ::= LWSChar*
+
+       LWSChar                 ::= LF | " " | TAB
+       OctChar                 ::= "0" | "1" | "2" | "3" | "4" | "5" | "6" | 
"7"
+       DecChar                 ::= OctChar | "8" | "9"
+       HexChar                 ::= DecChar | "a" | "b" | "c" | "d" | "e" | "A" 
| "B" | "C"
+                                               | "D" | "E"
+       Char                    :: <any character>
+       QChar                   ::= <Char except "\", "&", "'" and '"'> | 
EscapedChar
+       EscapedChar             ::= "\" Char
+       UChar                   ::= <QChar except LWSChar>
+
+       Conditions:
+       (checked)
+       - If a mask is specified for a pattern, this mask must have the same
+         length as the pattern string.
+       (not checked)
+       - 0 <= Priority <= 1
+       - 0 <= Range begin <= Range end
+       - Rules of the form "() | () | ..." are invalid.
+
+       Examples:
+       - 1.0 ('ABCD')
+         The file must start with the string "ABCD". The priority of the rule
+         is 1.0 (maximal).
+       - 0.8 [0:3] ('ABCD' | 'abcd')
+         The file must contain the string "ABCD" or "abcd" starting somewhere 
in
+         the first four bytes. The rule priority is 0.8.
+       - 0.5 ([0:3] 'ABCD' | [0:3] 'abcd' | [13] 'EFGH')
+         The file must contain the string "ABCD" or "abcd" starting somewhere 
in
+         the first four bytes or the string "EFGH" at position 13. The rule
+         priority is 0.5.
+       - 0.8 [0:3] ('ABCD' & 0xff00ffff | 'abcd' & 0xffff00ff)
+         The file must contain the string "A.CD" or "ab.d" (whereas "." is an
+         arbitrary character) starting somewhere in the first four bytes. The
+         rule priority is 0.8.
+
+       Real examples:
+       - 0.20 ([0]"//" | [0]"/\*" | [0:32]"#include" | [0:32]"#ifndef"
+               | [0:32]"#ifdef")
+         text/x-source-code
+       - 0.70 ("8BPS  \000\000\000\000" & 0xffffffff0000ffffffff )
+         image/x-photoshop
+\endverbatim
+
+       \param rule The rule string.
+       \param parseError A pointer to a pre-allocated BString into which a
+                  description of the parse error is written (if any), may be 
\c NULL.
+
+       \returns A status code.
+       \retval B_OK The supplied sniffer rule is valid.
+       \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.
+*/
+
+
+/*!
+       \fn status_t BMimeType::GuessMimeType(const entry_ref *file,
+               BMimeType *type)
+       \brief Guesses a MIME type for the entry referred to by the given
+               entry_ref.
+
+       This version of GuessMimeType() combines the features of the other
+       versions: First the data of the given file are checked (sniffed). Only
+       if the result of this operation is inconclusive, i.e.
+       "application/octet-stream", the filename is examined for extensions.
+
+       \param file Pointer to the entry_ref referring to the entry.
+       \param type Pointer to a pre-allocated BMimeType which is set to the
+                  resulting MIME type.
+
+       \returns A status code.
+       \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.
+*/
+
+
+/*!
+       \fn status_t BMimeType::GuessMimeType(const void *buffer, int32 length,
+               BMimeType *type)
+       \brief Guesses a MIME type for the supplied chunk of data.
+
+       \param buffer Pointer to the data buffer.
+       \param length Size of the buffer in bytes.
+       \param type Pointer to a pre-allocated BMimeType which is set to the
+                  resulting MIME type.
+
+       \returns A status code.
+       \retval B_OK Everything went fine.
+       \retval B_BAD_VALUE \c NULL \a buffer or \a result.
+*/
+
+
+/*!
+       \fn status_t BMimeType::GuessMimeType(const char *filename, BMimeType 
*type)
+       \brief Guesses a MIME type for the given filename.
+
+       Only the filename itself is taken into consideration (in particular its
+       name extension), not the entry it refers to. I.e. an entry with that 
name
+       doesn't need to exist at all.
+
+       \param filename The filename.
+       \param type Pointer to a pre-allocated BMimeType which is set to the
+                  resulting MIME type.
+
+       \returns A status code.
+       \retval B_OK Everything went fine.
+       \retval B_BAD_VALUE \c NULL \a ref or \a result.
+*/
+
+
+/*!
+       \fn status_t BMimeType::StartWatching(BMessenger target)
+       \brief Starts monitoring the MIME database for a given target.
+
+       Until StopWatching() is called for the target, an update message is sent
+       to it whenever the MIME database changes.
+
+       \param target A BMessenger identifying the target for the update 
messages.
+
+       \returns \c B_OK on success or another error code on failure.
+*/
+
+
+/*!
+       \fn status_t BMimeType::StopWatching(BMessenger target)
+       \brief Stops monitoring the MIME database for a given target (previously
+               started via StartWatching()).
+
+       \param target A BMessenger identifying the target for the update 
messages.
+
+       \returns \c B_OK on success or another error code on failure.
+*/
+
+
+/*!
+       \fn status_t BMimeType::SetType(const char *mimeType)
+       \brief Initializes this object to the supplied MIME type.
+
+       \deprecated This method has the same semantics as SetTo().
+                               Use SetTo() instead.
+*/
+
+
+/*!
+       \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.
+*/
+
+
diff --git a/src/kits/storage/MimeType.cpp b/src/kits/storage/MimeType.cpp
index 452a932..15c7794 100644
--- a/src/kits/storage/MimeType.cpp
+++ b/src/kits/storage/MimeType.cpp
@@ -70,8 +70,7 @@ isValidMimeChar(const char ch)
 //     #pragma mark -
 
 
-/*!    \brief Creates an uninitialized BMimeType object.
-*/
+// Creates an uninitialized BMimeType object.
 BMimeType::BMimeType()
        :
        fType(NULL),
@@ -80,12 +79,8 @@ BMimeType::BMimeType()
 }
 
 
-/*!    \brief Creates a BMimeType object and initializes it to the supplied
-       MIME type.
-       The supplied string must specify a valid MIME type or supertype.
-       \see SetTo() for further information.
-       \param mimeType The MIME string.
-*/
+// Creates a BMimeType object and initializes it to the supplied
+// MIME type.
 BMimeType::BMimeType(const char *mimeType)
        :
        fType(NULL),
@@ -95,36 +90,14 @@ BMimeType::BMimeType(const char *mimeType)
 }
 
 
-/*!    \brief Frees all resources associated with this object.
-*/
+// Frees all resources associated with this object.
 BMimeType::~BMimeType()
 {
        Unset();
 }
 
-// SetTo
-/*!    \brief Initializes this object to the supplied MIME type.
-       The supplied string must specify a valid MIME type or supertype.
-       Valid MIME types are given by the following grammar:
-       MIMEType        ::= Supertype "/" [ Subtype ]
-       Supertype       ::= "application" | "audio" | "image" | "message"
-                                       | "multipart" | "text" | "video"
-       Subtype         ::= MIMEChar MIMEChar*
-       MIMEChar        ::= any character except white spaces, CTLs and '/', 
'<', '>',
-                                       '@',, ',', ';', ':', '"', '(', ')', 
'[', ']', '?', '=', '\'
-                                       (Note: RFC1341 also forbits '.', but it 
is allowed here.)
-
-       Currently the supertype is not restricted to one of the seven types 
given,
-       but can be an arbitrary string (obeying the same rule as the subtype).
-       Nevertheless it is a very bad idea to use another supertype.
-       The supplied MIME string is copied; the caller retains the ownership.
-       \param mimeType The MIME string.
-       \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_MEMORY Insufficient memory to copy the MIME string.
-*/
+
+// Initializes this object to the supplied MIME type.
 status_t
 BMimeType::SetTo(const char *mimeType)
 {
@@ -145,9 +118,8 @@ BMimeType::SetTo(const char *mimeType)
        return fCStatus;
 }
 
-// Unset
-/*!    \brief Returns the object to an uninitialized state.
-*/
+
+// Returns the object to an uninitialized state
 void
 BMimeType::Unset()
 {
@@ -156,46 +128,32 @@ BMimeType::Unset()
        fCStatus = B_NO_INIT;
 }
 
-// InitCheck
-/*!    Returns the result of the most recent constructor or SetTo() call.
-       \return
-       - \c B_OK: The object is properly initialized.
-       - A specific error code otherwise.
-*/
+
+// Returns the result of the most recent constructor or SetTo() call
 status_t
 BMimeType::InitCheck() const
 {
        return fCStatus;
 }
 
-// Type
-/*!    \brief Returns the MIME string represented by this object.
-       \return The MIME string, if the object is properly initialized, \c NULL
-                       otherwise.
-*/
-const char *
+
+// Returns the MIME string represented by this object
+const char*
 BMimeType::Type() const
 {
        return fType;
 }
 
-// IsValid
-/*!    \brief Returns whether the object represents a valid MIME type.
-       \see SetTo() for further information.
-       \return \c true, if the object is properly initialized, \c false
-                       otherwise.
-*/
+
+// Returns whether the object represents a valid MIME type
 bool
 BMimeType::IsValid() const
 {
        return InitCheck() == B_OK && BMimeType::IsValid(Type());
 }
 
-// IsSupertypeOnly
-/*!    \brief Returns whether this objects represents a supertype.
-       \return \c true, if the object is properly initialized and represents a
-                       supertype, \c false otherwise.
-*/
+
+// Returns whether this objects represents a supertype
 bool
 BMimeType::IsSupertypeOnly() const
 {
@@ -212,32 +170,17 @@ BMimeType::IsSupertypeOnly() const
                return false;
 }
 
-// IsInstalled
-//! Returns whether or not this type is currently installed in the MIME 
database
-/*! To add the MIME type to the database, call \c Install().
-       To remove the MIME type from the database, call \c Delete().
 
-       \return
-       - \c true: The MIME type is currently installed in the database
-       - \c false: The MIME type is not currently installed in the database
-*/
+// Returns whether or not this type is currently installed in the
+// MIME database
 bool
 BMimeType::IsInstalled() const
 {
        return InitCheck() == B_OK && is_installed(Type());
 }
 
-// GetSupertype
-/*!    \brief Gets the supertype of the MIME type represented by this object.
-       The supplied object is initialized to this object's 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
-                  initialized to this object's 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.
-*/
+
+// Gets the supertype of the MIME type represented by this object
 status_t
 BMimeType::GetSupertype(BMimeType *superType) const
 {
@@ -267,15 +210,8 @@ BMimeType::GetSupertype(BMimeType *superType) const
        return status;
 }
 
-// ==
-/*!    \brief Returns whether this and the supplied MIME type are equal.
-       Two BMimeType objects are said to be equal if they represent the same
-       MIME string, ignoring case, or if both are not initialized.
-       \warning In BeOS R5 two uninitialized BMimeType objects were not
-               considered to be equal, in Haiku they are.
-       \param type The BMimeType to be compared with.
-       \return \c true, if the objects are equal, \c false otherwise.
-*/
+
+// Returns whether this and the supplied MIME type are equal
 bool
 BMimeType::operator==(const BMimeType &type) const
 {
@@ -287,16 +223,8 @@ BMimeType::operator==(const BMimeType &type) const
        return false;
 }
 
-// ==
-/*!    \brief Returns whether this and the supplied MIME type are equal.
-       A BMimeType objects equals a MIME string, if its MIME string equals the
-       latter one, ignoring case, or if it is uninitialized and the MIME string
-       is \c NULL.
-       \warning In BeOS R5 an uninitialized BMimeType object was not
-               considered to be equal to \c NULL, in Haiku it is.
-       \param type The MIME string to be compared with.
-       \return \c true, if the MIME types are equal, \c false otherwise.
-*/
+
+// Returns whether this and the supplied MIME type are equal
 bool
 BMimeType::operator==(const char *type) const
 {
@@ -306,13 +234,9 @@ BMimeType::operator==(const char *type) const
        return (*this) == mime;
 }
 
-// Contains
-/*!    \brief Returns whether this MIME type is a supertype of or equals the
-       supplied one.
-       \param type The MIME type.
-       \return \c true, if this MIME type is a supertype of or equals the
-                       supplied one, \c false otherwise.
-*/
+
+// Returns whether this MIME type is a supertype of or equals the
+// supplied one
 bool
 BMimeType::Contains(const BMimeType *type) const
 {
@@ -326,348 +250,148 @@ BMimeType::Contains(const BMimeType *type) const
        return false;   
 }
 
-// Install
-//! Adds the MIME type to the MIME database
-/*! To check if the MIME type is already installed, call \c IsInstalled().
-       To remove the MIME type from the database, call \c Delete().
-       
-       \note The R5 implementation returns random values if the type is already
-       installed, so be sure to check \c IsInstalled() first.
-       
-       \return
-       - \c B_OK: Success
-       - other error code: Failure
-*/
+
+// Adds the MIME type to the MIME database
 status_t
 BMimeType::Install()
 {
-       status_t err = InitCheck();     
+       status_t err = InitCheck();
 
        BMessage msg(B_REG_MIME_INSTALL);
        BMessage reply;
        status_t result;
-       
+
        // Build and send the message, read the reply
        if (!err)
                err = msg.AddString("type", Type());
-       if (!err) 
+       if (!err)
                err = BRoster::Private().SendTo(&msg, &reply, true);
        if (!err)
-               err = reply.what == B_REG_RESULT ? (status_t)B_OK : 
(status_t)B_BAD_REPLY;
+               err = (status_t)(reply.what == B_REG_RESULT ? B_OK : 
B_BAD_REPLY);
        if (!err)
                err = reply.FindInt32("result", &result);
        if (!err) 
-               err = result;   
+               err = result;
+
        return err;     
 }
 
-// Delete
-//! Removes the MIME type from the MIME database
-/*! To check if the MIME type is already installed, call \c IsInstalled().
-       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
-       database.
-       
-       \return
-       - \c B_OK: Success
-       - other error code: Failure
-*/
+
+// Removes the MIME type from the MIME database
 status_t
 BMimeType::Delete()
 {
-       status_t err = InitCheck();     
+       status_t err = InitCheck();
 
        BMessage msg(B_REG_MIME_DELETE);
        BMessage reply;
        status_t result;
-       
+
        // Build and send the message, read the reply
        if (!err)
                err = msg.AddString("type", Type());
-       if (!err) 
+       if (!err)
                err = BRoster::Private().SendTo(&msg, &reply, true);
        if (!err)
-               err = reply.what == B_REG_RESULT ? (status_t)B_OK : 
(status_t)B_BAD_REPLY;
+               err = (status_t)(reply.what == B_REG_RESULT ? B_OK : 
B_BAD_REPLY);
        if (!err)
                err = reply.FindInt32("result", &result);
-       if (!err) 
-               err = result;   
-       return err;     
+       if (!err)
+               err = result;
+
+       return err;
 }
 
-// GetIcon
-//! Fetches the large or mini icon associated with the MIME type
-/*! The icon is copied into the \c BBitmap pointed to by \c icon. The bitmap 
must
-       be the proper size: \c 32x32 for the large icon, \c 16x16 for the mini 
icon.    
-       Additionally, the bitmap must be in the \c B_CMAP8 color space (8-bit 
color).
-       
-       \param icon Pointer to a pre-allocated \c BBitmap of proper size and 
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
-       - other error code: Failure     
-
-*/
+
+// Fetches the large or mini icon associated with the MIME type
 status_t
 BMimeType::GetIcon(BBitmap *icon, icon_size size) const
 {
        status_t err = InitCheck();
        if (!err)
                err = get_icon(Type(), icon, size);
+
        return err;
 }
 
 
-/*!    \brief Fetches the vector icon associated with the MIME type
-       The icon data is returned in \c data.
-
-       \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.
-       \return
-       - \c B_OK: Success
-       - \c B_ENTRY_NOT_FOUND: No icon of the given size exists for the given 
type
-       - other error code: Failure     
-
-*/
+//     Fetches the vector icon associated with the MIME type
 status_t
 BMimeType::GetIcon(uint8** data, size_t* size) const
 {
        status_t err = InitCheck();
        if (!err)
                err = get_icon(Type(), data, size);
+
        return err;
 }
 
 
-// GetPreferredApp
-//! Fetches the signature of the MIME type's preferred application from the 
MIME database
-/*! The preferred app is the application that's used to access a file when, 
for example, the user
-       double-clicks the file in a Tracker window. Unless the file identifies 
in its attributes a
-       "custom" preferred app, Tracker will ask the file type database for the 
preferred app
-       that's associated with the file's type.
-       
-       The string pointed to by \c signature must be long enough to
-       hold the preferred applications signature; a length of \c 
B_MIME_TYPE_LENGTH is
-       recommended.
-       
-       \param signature Pointer to a pre-allocated string into which the 
signature of the preferred app is copied. If
-                          the function fails, the contents of the string are 
undefined.
-       \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.
-       \return
-       - \c B_OK: Success
-       - \c B_ENTRY_NOT_FOUND: No preferred app exists for the given type and 
app_verb
-       - other error code: Failure
-*/
+// Fetches the signature of the MIME type's preferred application from the
+// MIME database
 status_t
 BMimeType::GetPreferredApp(char *signature, app_verb verb) const
 {
        status_t err = InitCheck();
        if (!err)
                err = get_preferred_app(Type(), signature, verb);
+
        return err;
 }
 
-// GetAttrInfo
-/*! \brief 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 by
-       the \c info parameter (note that the any prior contents of the message
-       will be destroyed). If the method succeeds, the format of the BMessage
-       pointed to by \c info will be the following:
-       
-       <table>
-               <tr>
-                       <td><b>field name</b></td>
-                       <td><b>type</b></td>
-                       <td><b>element[0..n]</b></td>
-               </tr>
-               <tr>
-                       <td> "attr:name"</td>
-                       <td> \c B_STRING_TYPE </td>
-                       <td> The name of each attribute </td>
-               </tr>
-               <tr>
-                       <td> "attr:public_name"</td>
-                       <td> \c B_STRING_TYPE </td>
-                       <td> The human-readable name of each attribute </td>
-               </tr>
-               <tr>
-                       <td> "attr:type"</td>
-                       <td> \c B_INT32_TYPE </td>
-                       <td> The type code for each attribute </td>
-               </tr>
-               <tr>
-                       <td> "attr:viewable"</td>
-                       <td> \c B_BOOL_TYPE </td>
-                       <td> For each attribute: \c true if the attribute is 
public, \c false if it's private </td>
-               </tr>
-               <tr>
-                       <td> "attr:editable"</td>
-                       <td> \c B_BOOL_TYPE </td>
-                       <td> For each attribute: \c true if the attribute 
should be user editable, \c false if not </td>
-               </tr>
-       </table>
-       
-       The \c BMessage::what value is set to decimal \c 233, but is otherwise 
meaningless.
-       
-       \param info Pointer to a pre-allocated BMessage into which information 
about
-                   the MIME type's associated file attributes is stored.
-       \return
-       - \c B_OK: Success
-       - other error code: Failure
-*/
+
+// Fetches from the MIME database a BMessage describing the attributes
+// typically associated with files of the given MIME type
 status_t
 BMimeType::GetAttrInfo(BMessage *info) const
 {
        status_t err = InitCheck();
        if (!err)
                err = get_attr_info(Type(), info);
+
        return err;
 }
 
-// GetFileExtensions
-//! Fetches the MIME type's associated filename extensions from the MIME 
database
-/*! The MIME database associates a list of filename extensions (a character 
string
-       following the rightmost dot, \c ".", character in the filename) with 
each type.
-       These extensions can then be used to help determine the type of any 
untyped files
-       that may be     encountered.
-
-       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 
message
-       will be destroyed). If the method succeeds, the format of the BMessage
-       pointed to by \c extensions will be the following:
-       - The message's \c "extensions" field will contain an indexed array of 
strings,
-         one for each extension. The extensions are given without the 
preceding \c "."
-         character by convention. 
-       - The message's \c "type" field will be a string containing the MIME 
type whose
-         associated file extensions you are fetching.
-       - The \c what member of the BMessage will be set to \c 234, but is 
otherwise
-         irrelevant.
-         
-       Note that any other fields present in the BMessage passed to the most 
recent
-       \c SetFileExtensions() call will also be returned.
-         
-       \param extensions Pointer to a pre-allocated BMessage into which the
-                         MIME type's associated file extensions will be stored.
-       \return
-       - \c B_OK: Success
-       - other error code: Failure
-*/
+
+// Fetches the MIME type's associated filename extensions from the MIME
+// database
 status_t
 BMimeType::GetFileExtensions(BMessage *extensions) const
 {
        status_t err = InitCheck();
        if (!err)
                err = get_file_extensions(Type(), extensions);
+
        return err;
 }
 
-// GetShortDescription
-//! Fetches the MIME type's short description from the MIME database
-/*! 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
-       recommended.
-       
-       \param description Pointer to a pre-allocated string into which the 
long description is copied. If
-                          the function fails, the contents of the string are 
undefined.
-       \return
-       - \c B_OK: Success
-       - \c B_ENTRY_NOT_FOUND: No short description exists for the given type
-       - other error code: Failure
-*/
+
+// Fetches the MIME type's short description from the MIME database
 status_t
 BMimeType::GetShortDescription(char *description) const
 {
        status_t err = InitCheck();
        if (!err)
                err = get_short_description(Type(), description);
+
        return err;
 }
 
-// GetLongDescription
-//! Fetches the MIME type's long description from the MIME database
-/*! 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 description Pointer to a pre-allocated string into which the 
long description is copied. If
-                          the function fails, the contents of the string are 
undefined.
-       \return
-       - \c B_OK: Success
-       - \c B_ENTRY_NOT_FOUND: No long description exists for the given type
-       - other error code: Failure
-*/
+
+// Fetches the MIME type's long description from the MIME database
 status_t
 BMimeType::GetLongDescription(char *description) const
 {
        status_t err = InitCheck();
        if (!err)
                err = get_long_description(Type(), description);
+
        return err;
 }
 
-// GetSupportingApps
-/*! \brief Fetches a \c BMessage containing a list of MIME signatures of
-       applications that are able to handle files of this MIME type.
-       
-       If successful, the BMessage containing the MIME signatures will be of
-       the following format:
-       
-       <table>
-               <tr>
-                       <td><b>field name</b></td>
-                       <td><b>type</b></td>
-                       <td><b>contains</b></td>
-               </tr>
-               <tr>
-                       <td> "applications"</td>
-                       <td> \c B_STRING_TYPE[] </td>
-                       <td>
-                       An array of MIME signatures. The first <i> n </i> 
signatures (where
-                       <i> n </i> is the value in the \c "be:sub" field of the 
message) are able
-                       to handle the full type (supertype <i> and </i> 
subtype). The remaining
-                       signatures are of applications that handle the 
supertype only.
-                       </td>
-               </tr>
-               <tr>
-                       <td> "be:sub"</td>
-                       <td> \c B_INT32_TYPE </td>
-                       <td>
-                       The number of applications in the \c "applications" 
array that
-                       can handle the object's full MIME type. These 
applications are listed
-                       first in the array. This field is omitted if the object 
represents a
-                       supertype only.
-                       </td>
-               </tr>
-               <tr>
-                       <td> "be:super"</td>
-                       <td> \c B_INT32_TYPE </td>
-                       <td>
-                       The number of applications in the "applications" array 
that can handle
-                       the object's supertype (not counting those that can 
handle the full type).
-                       These applications are listed after the full-MIME-type 
supporters. By
-                       definition, the \c GetWildcardApps() function never 
returns supertype-only
-                       apps.
-                       </td>
-               </tr>
-       </table>
-       
-       The \c BMessage::what value is meaningless and should be ignored.
-       
-       \param signatures Pointer to a pre-allocated BMessage into which the 
signatures
-                         of the supporting applications will be copied.
-       \return
-       - \c B_OK: Success
-       - other error code: Failure     
-*/
+
+// Fetches a \c BMessage containing a list of MIME signatures of
+// applications that are able to handle files of this MIME type.
 status_t
 BMimeType::GetSupportingApps(BMessage *signatures) const
 {
@@ -680,91 +404,48 @@ BMimeType::GetSupportingApps(BMessage *signatures) const
        status_t err = InitCheck();
        if (!err)
                err = msg.AddString("type", Type());
-       if (!err) 
-               err = BRoster::Private().SendTo(&msg, signatures, true);
        if (!err)
-               err = signatures->what == B_REG_RESULT ? (status_t)B_OK : 
(status_t)B_BAD_REPLY;
+               err = BRoster::Private().SendTo(&msg, signatures, true);
+       if (!err) {
+               err = (status_t)(signatures->what == B_REG_RESULT ? B_OK
+                       : B_BAD_REPLY);
+       }
        if (!err)
                err = signatures->FindInt32("result", &result);
        if (!err) 
                err = result;
 
-       return err;     
+       return err;
 }
 
-// SetIcon
-//! Sets the large or mini icon for the MIME type
-/*! The icon is copied from the \c BBitmap pointed to by \c icon. The bitmap 
must
-       be the proper size: \c 32x32 for the large icon, \c 16x16 for the mini 
icon.    
-       Additionally, the bitmap must be in the \c B_CMAP8 color space (8-bit 
color).
-       
-       If you want to erase the current icon, pass \c NULL as the \c icon 
argument.
-       
-       \param icon Pointer to a pre-allocated \c BBitmap of proper size and 
colorspace
-                               containing the new icon, or \c NULL to clear 
the current icon.
-       \param icon_size Value that specifies which icon to update. Currently 
\c B_LARGE_ICON
-                                        and \c B_MINI_ICON are supported.
-       \return
-       - \c B_OK: Success
-       - other error code: Failure     
- 
-*/
+
+// Sets the large or mini icon for the MIME type
 status_t
 BMimeType::SetIcon(const BBitmap *icon, icon_size which)
 {
        return SetIconForType(NULL, icon, which);
 }
 
-// SetIcon
-//! Sets the vector icon for the MIME type
-/*! The icon is copied from the provided \a data which must contain \a size 
bytes.
-       
-       If you want to erase the current icon, pass \c NULL as the \a data 
argument.
-       
-       \param data Pointer to a buffer containing the new icon, or \c NULL to 
clear
-                               the current icon.
-       \param size Size of the provided buffer.
-       \return
-       - \c B_OK: Success
-       - other error code: Failure     
- 
-*/
+
+// Sets the vector icon for the MIME type
 status_t
 BMimeType::SetIcon(const uint8* data, size_t size)
 {
        return SetIconForType(NULL, data, size);
 }
 
-// SetPreferredApp
-//! Sets the preferred application for the MIME type
-/*! The preferred app is the application that's used to access a file when, 
for example, the user
-       double-clicks the file in a Tracker window. Unless the file identifies 
in its attributes a
-       "custom" preferred app, Tracker will ask the file type database for the 
preferred app
-       that's associated with the file's type.
-       
-       The string pointed to by \c signature must be of
-       length less than \c B_MIME_TYPE_LENGTH characters.
-       
-       \note If the MIME type is not installed, it will first be installed, 
and then
-       the preferred app will be set.
-
-       \param signature Pointer to a pre-allocated string containing the 
signature of the new preferred app.
-       \param verb \c app_verb value that specifies the type of access for 
which you are setting the preferred app.
-                   Currently, the only supported app verb is \c B_OPEN.
-       \return
-       - \c B_OK: Success
-       - other error code: Failure
-*/
+
+// Sets the preferred application for the MIME type
 status_t
 BMimeType::SetPreferredApp(const char *signature, app_verb verb)
 {
-       status_t err = InitCheck();     
+       status_t err = InitCheck();
 
        BMessage msg(signature && signature[0]
                ? B_REG_MIME_SET_PARAM : B_REG_MIME_DELETE_PARAM);
        BMessage reply;
        status_t result;
-       
+
        // Build and send the message, read the reply
        if (!err)
                err = msg.AddString("type", Type());
@@ -774,75 +455,30 @@ BMimeType::SetPreferredApp(const char *signature, 
app_verb verb)
                err = msg.AddString("signature", signature);
        if (!err)
                err = msg.AddInt32("app verb", verb);
-       if (!err) 
+       if (!err)
                err = BRoster::Private().SendTo(&msg, &reply, true);
        if (!err)
-               err = reply.what == B_REG_RESULT ? (status_t)B_OK : 
(status_t)B_BAD_REPLY;
+               err = (status_t)(reply.what == B_REG_RESULT ? B_OK : 
B_BAD_REPLY);
        if (!err)
                err = reply.FindInt32("result", &result);
-       if (!err) 
-               err = result;   
-       return err;     
+       if (!err)
+               err = result;
+
+       return err;
 }
 
-// SetAttrInfo
-/*! \brief Sets the description of the attributes typically associated with 
files
-       of the given MIME type
-       
-       The attribute information is technically arbitrary, but the expected
-       format of the BMessage pointed to by the \c info parameter is as 
follows:
-       
-       <table>
-               <tr>
-                       <td><b>field name</b></td>
-                       <td><b>type</b></td>
-                       <td><b>element[0..n]</b></td>
-               </tr>
-               <tr>
-                       <td> "attr:name"</td>
-                       <td> \c B_STRING_TYPE </td>
-                       <td> The name of each attribute </td>
-               </tr>
-               <tr>
-                       <td> "attr:public_name"</td>
-                       <td> \c B_STRING_TYPE </td>
-                       <td> The human-readable name of each attribute </td>
-               </tr>
-               <tr>
-                       <td> "attr:type"</td>
-                       <td> \c B_INT32_TYPE </td>
-                       <td> The type code for each attribute </td>
-               </tr>
-               <tr>
-                       <td> "attr:viewable"</td>
-                       <td> \c B_BOOL_TYPE </td>
-                       <td> For each attribute: \c true if the attribute is 
public, \c false if it's private </td>
-               </tr>
-               <tr>
-                       <td> "attr:editable"</td>
-                       <td> \c B_BOOL_TYPE </td>
-                       <td> For each attribute: \c true if the attribute 
should be user editable, \c false if not </td>
-               </tr>
-       </table>
-       
-       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 
with the
-                   MIME type.
-       \return
-       - \c B_OK: Success
-       - other error code: Failure
-*/
+
+// Sets the description of the attributes typically associated with files
+// of the given MIME type
 status_t
 BMimeType::SetAttrInfo(const BMessage *info)
 {
-       status_t err = InitCheck();     
+       status_t err = InitCheck();
 
        BMessage msg(info ? B_REG_MIME_SET_PARAM : B_REG_MIME_DELETE_PARAM);
        BMessage reply;
        status_t result;
-       
+
        // Build and send the message, read the reply
        if (!err)
                err = msg.AddString("type", Type());
@@ -850,56 +486,29 @@ BMimeType::SetAttrInfo(const BMessage *info)
                err = msg.AddInt32("which", B_REG_MIME_ATTR_INFO);
        if (!err && info) 
                err = msg.AddMessage("attr info", info);
-       if (!err) 
+       if (!err)
                err = BRoster::Private().SendTo(&msg, &reply, true);
        if (!err)
-               err = reply.what == B_REG_RESULT ? (status_t)B_OK : 
(status_t)B_BAD_REPLY;
+               err = (status_t)(reply.what == B_REG_RESULT ? B_OK : 
B_BAD_REPLY);
        if (!err)
                err = reply.FindInt32("result", &result);
-       if (!err) 
-               err = result;   
-       return err;     
+       if (!err)
+               err = result;
+
+       return err;
 }
 
-// SetFileExtensions
-//! Sets the list of filename extensions associated with the MIME type
-/*! The MIME database associates a list of filename extensions (a character 
string
-       following the rightmost dot, \c ".", character in the filename) with 
each type.
-       These extensions can then be used to help determine the type of any 
untyped files
-       that may be     encountered.
-
-       The list of extensions is given in a pre-allocated BMessage pointed to 
by
-       the \c extensions parameter. The format of the message should be as 
follows:
-       - The message's \c "extensions" field should contain an indexed array 
of strings,
-         one for each extension. The extensions are to be given without the 
preceding \c "."
-         character (i.e. \c "html" or \c "mp3", not \c ".html" or \c ".mp3" ).
-       - The \c what member of the BMessage is ignored.
-         
-       Note that any other fields present in the \c BMessage will currently be 
retained
-       and returned by calls to \c GetFileExtensions(); however, this may 
change in the
-       future, so it is recommended that you not rely on this behaviour, and 
that no other
-       fields be present. Also, note that no checking is performed to verify 
the \c BMessage is
-       properly 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 
retrieve the
-       existing set, add the new ones, and then call \c SetFileExtensions(). 
-                 
-       \param extensions Pointer to a pre-allocated, properly formatted 
BMessage containing
-                         the new list of file extensions to associate with 
this MIME type.
-       \return
-       - \c B_OK: Success
-       - other error code: Failure
-*/
+
+// Sets the list of filename extensions associated with the MIME type
 status_t
 BMimeType::SetFileExtensions(const BMessage *extensions)
 {
-       status_t err = InitCheck();     
+       status_t err = InitCheck();
 
        BMessage msg(extensions ? B_REG_MIME_SET_PARAM : 
B_REG_MIME_DELETE_PARAM);
        BMessage reply;
        status_t result;
-       
+
        // Build and send the message, read the reply
        if (!err)
                err = msg.AddString("type", Type());
@@ -907,116 +516,87 @@ BMimeType::SetFileExtensions(const BMessage *extensions)
                err = msg.AddInt32("which", B_REG_MIME_FILE_EXTENSIONS);
        if (!err && extensions) 
                err = msg.AddMessage("extensions", extensions);
-       if (!err) 
+       if (!err)
                err = BRoster::Private().SendTo(&msg, &reply, true);
        if (!err)
-               err = reply.what == B_REG_RESULT ? (status_t)B_OK : 
(status_t)B_BAD_REPLY;
+               err = (status_t)(reply.what == B_REG_RESULT ? B_OK : 
B_BAD_REPLY);
        if (!err)
                err = reply.FindInt32("result", &result);
-       if (!err) 
-               err = result;   
-       return err;     
+       if (!err)
+               err = result;
+
+       return err;
 }
 
-// SetShortDescription
-//! Sets the short description field for the MIME type
-/*! The string pointed to by \c description must be of
-       length less than \c B_MIME_TYPE_LENGTH characters.
-       
-       \note If the MIME type is not installed, it will first be installed, 
and then
-       the short description will be set.
-
-       \param description Pointer to a pre-allocated string containing the new 
short description
-       \return
-       - \c B_OK: Success
-       - other error code: Failure
-*/
+
+// Sets the short description field for the MIME type
 status_t
 BMimeType::SetShortDescription(const char *description)
 {
-       status_t err = InitCheck();     
+       status_t err = InitCheck();
 
        BMessage msg(description && description [0]
                ? B_REG_MIME_SET_PARAM : B_REG_MIME_DELETE_PARAM);
        BMessage reply;
        status_t result;
-       
+
        // Build and send the message, read the reply
        if (!err)
                err = msg.AddString("type", Type());
-       if (!err) 
+       if (!err)
                err = msg.AddInt32("which", B_REG_MIME_DESCRIPTION);
        if (!err && description) 
                err = msg.AddString("description", description);
        if (!err)
                err = msg.AddBool("long", false);
-       if (!err) 
+       if (!err)
                err = BRoster::Private().SendTo(&msg, &reply, true);
        if (!err)
-               err = reply.what == B_REG_RESULT ? (status_t)B_OK : 
(status_t)B_BAD_REPLY;
+               err = (status_t)(reply.what == B_REG_RESULT ? B_OK : 
B_BAD_REPLY);
        if (!err)
                err = reply.FindInt32("result", &result);
-       if (!err) 
-               err = result;   
-       return err;     
+       if (!err)
+               err = result;
+
+       return err;
 }
 
-// SetLongDescription
-//! Sets the long description field for the MIME type
-/*! The string pointed to by \c description must be of
-       length less than \c B_MIME_TYPE_LENGTH characters.
-       
-       \note If the MIME type is not installed, it will first be installed, 
and then
-       the long description will be set.
-
-       \param description Pointer to a pre-allocated string containing the new 
long description
-       \return
-       - \c B_OK: Success
-       - other error code: Failure
-*/
+
+// Sets the long description field for the MIME type
 status_t
 BMimeType::SetLongDescription(const char *description)
 {
-       status_t err = InitCheck();     
+       status_t err = InitCheck();
 
        BMessage msg(description && description[0]
                ? B_REG_MIME_SET_PARAM : B_REG_MIME_DELETE_PARAM);
        BMessage reply;
        status_t result;
-       
+
        // Build and send the message, read the reply
        if (!err)
                err = msg.AddString("type", Type());
-       if (!err) 
+       if (!err)
                err = msg.AddInt32("which", B_REG_MIME_DESCRIPTION);
        if (!err && description) 
                err = msg.AddString("description", description);
        if (!err)
                err = msg.AddBool("long", true);
-       if (!err) 
+       if (!err)
                err = BRoster::Private().SendTo(&msg, &reply, true);
        if (!err)
-               err = reply.what == B_REG_RESULT ? (status_t)B_OK : 
(status_t)B_BAD_REPLY;
+               err = (status_t)(reply.what == B_REG_RESULT ? B_OK : 
B_BAD_REPLY);
        if (!err)
                err = reply.FindInt32("result", &result);
-       if (!err) 
-               err = result;   
-       return err;     
+       if (!err)
+               err = result;
+
+       return err;
 }
 
-// GetInstalledSupertypes
-/*! \brief Fetches a BMessage listing all the MIME 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.
-       \return
-       - \c B_OK: Success
-       - other error code: Failure
-*/
+// Fetches a BMessage listing all the MIME supertypes currently
+// installed in the MIME database.
 /*static*/ status_t
 BMimeType::GetInstalledSupertypes(BMessage *supertypes)
 {
@@ -1027,8 +607,10 @@ BMimeType::GetInstalledSupertypes(BMessage *supertypes)
        status_t result;
 
        status_t err = BRoster::Private().SendTo(&msg, supertypes, true);
-       if (!err)
-               err = supertypes->what == B_REG_RESULT ? (status_t)B_OK : 
(status_t)B_BAD_REPLY;
+       if (!err) {
+               err = (status_t)(supertypes->what == B_REG_RESULT ? B_OK
+                       : B_BAD_REPLY);
+       }
        if (!err)
                err = supertypes->FindInt32("result", &result);
        if (!err)
@@ -1037,40 +619,18 @@ BMimeType::GetInstalledSupertypes(BMessage *supertypes)
        return err;     
 }
 
-// GetInstalledTypes
-/*! \brief Fetches a BMessage listing all the MIME types currently installed
-       in the MIME database.
-       
-       The types are copied into the \c "types" field of the passed-in \c 
BMessage.
-       The \c BMessage must be pre-allocated.
-       
-       \param types Pointer to a pre-allocated \c BMessage into which the 
-                    MIME types will be copied.
-       \return
-       - \c B_OK: Success
-       - other error code: Failure
-*/
+
+// Fetches a BMessage listing all the MIME types currently installed
+// in the MIME database.
 status_t
 BMimeType::GetInstalledTypes(BMessage *types)
 {
        return GetInstalledTypes(NULL, types);
 }
 
-// GetInstalledTypes
-/*! \brief Fetches a BMessage listing all the MIME subtypes of the given
-       supertype currently installed in the MIME database.
-       
-       The types are copied into the \c "types" field of the passed-in \c 
BMessage.
-       The \c BMessage must be pre-allocated.
-       
-       \param super_type Pointer to a string containing the MIME supertype 
whose
-                         subtypes you wish to retrieve.
-       \param subtypes Pointer to a pre-allocated \c BMessage into which the 
appropriate
-                       MIME subtypes will be copied.
-       \return
-       - \c B_OK: Success
-       - other error code: Failure             
-*/
+
+// Fetches a BMessage listing all the MIME subtypes of the given
+// supertype currently installed in the MIME database.
 /*static*/ status_t
 BMimeType::GetInstalledTypes(const char *supertype, BMessage *types)
 {
@@ -1080,15 +640,15 @@ BMimeType::GetInstalledTypes(const char *supertype, 
BMessage *types)
        status_t result;
 
        // Build and send the message, read the reply
-
        BMessage msg(B_REG_MIME_GET_INSTALLED_TYPES);
        status_t err = B_OK;
+
        if (supertype != NULL)
                err = msg.AddString("supertype", supertype);
        if (!err)
                err = BRoster::Private().SendTo(&msg, types, true);
        if (!err)
-               err = types->what == B_REG_RESULT ? (status_t)B_OK : 
(status_t)B_BAD_REPLY;
+               err = (status_t)(types->what == B_REG_RESULT ? B_OK : 
B_BAD_REPLY);
        if (!err)
                err = types->FindInt32("result", &result);
        if (!err)
@@ -1097,22 +657,9 @@ BMimeType::GetInstalledTypes(const char *supertype, 
BMessage *types)
        return err;
 }
 
-// GetWildcardApps
-/*! \brief Fetches a \c BMessage containing a list of MIME signatures of
-       applications that are able to handle files of any type.
 
-       This function is the same as calling \c GetSupportingApps() on a
-       \c BMimeType object initialized to a MIME type of \c 
"application/octet-stream".
-
-       \see GetSupportingApps() for details on the format of the data returned 
in
-       the \c BMessage pointed to by \c wild_ones.
-
-       \param wild_ones Pointer to a pre-allocated BMessage into which 
signatures of
-                        applications supporting files of any type are copied.
-       \return
-       - \c B_OK: Success
-       - other error code: Failure     
-*/
+// Fetches a \c BMessage containing a list of MIME signatures of
+// applications that are able to handle files of any type.
 status_t
 BMimeType::GetWildcardApps(BMessage *wild_ones)
 {
@@ -1123,11 +670,8 @@ BMimeType::GetWildcardApps(BMessage *wild_ones)
        return err;
 }
 
-// IsValid
-/*!    \brief Returns whether the given string represents a valid MIME type.
-       \see SetTo() for further information.
-       \return \c true, if the given string represents a valid MIME type.
-*/
+
+// Returns whether the given string represents a valid MIME type.
 bool
 BMimeType::IsValid(const char *string)
 {
@@ -1154,23 +698,8 @@ BMimeType::IsValid(const char *string)
 }
 
 
-// GetAppHint
-//! Fetches an \c entry_ref that serves as a hint as to where the MIME type's 
preferred application might live
-/*! The app hint is a path that identifies the executable that should be used 
when launching an application
-       that has this signature. For example, when Tracker needs to launch an 
app of type \c "application/YourAppHere",
-       it asks the database for the application hint. This hint is converted 
to an \c entry_ref before it is passed
-       to the caller. Of course, the path may not point to an application, or 
it might point to an application
-       with the wrong signature (and so on); that's why this is merely a hint.
-
-       The \c entry_ref pointed to by \c ref must be pre-allocated.
-
-       \param ref Pointer to a pre-allocated \c entry_ref into which the 
location of the app hint is copied. If
-                          the function fails, the contents of the \c entry_ref 
are undefined.
-       \return
-       - \c B_OK: Success
-       - \c B_ENTRY_NOT_FOUND: No app hint exists for the given type
-       - other error code: Failure
-*/
+// Fetches an \c entry_ref that serves as a hint as to where the MIME type's
+// preferred application might live
 status_t
 BMimeType::GetAppHint(entry_ref *ref) const
 {
@@ -1180,80 +709,39 @@ BMimeType::GetAppHint(entry_ref *ref) const
        return err;
 }
 
-// SetAppHint
-//! Sets the app hint field for the MIME type
-/*! The app hint is a path that identifies the executable that should be used 
when launching an application
-       that has this signature. For example, when Tracker needs to launch an 
app of type \c "application/YourAppHere",
-       it asks the database for the application hint. This hint is converted 
to an \c entry_ref before it is passed
-       to the caller. Of course, the path may not point to an application, or 
it might point to an application
-       with the wrong signature (and so on); that's why this is merely a hint.
-
-       The \c entry_ref pointed to by \c ref must be pre-allocated. It must be 
a valid \c entry_ref (i.e. 
-       <code>entry_ref(-1, -1, "some_file")</code> will trigger an error), but 
it need not point to an existing file, nor need
-       it actually point to an application. That's not to say that it 
shouldn't; such an \c entry_ref would
-       render the app hint useless.
-
-       \param ref Pointer to a pre-allocated \c entry_ref containting the 
location of the new app hint
-       \return
-       - \c B_OK: Success
-       - other error code: Failure
-*/
+
+// Sets the app hint field for the MIME type
 status_t
 BMimeType::SetAppHint(const entry_ref *ref)
 {
-       status_t err = InitCheck();     
+       status_t err = InitCheck();
 
        BMessage msg(ref ? B_REG_MIME_SET_PARAM : B_REG_MIME_DELETE_PARAM);
        BMessage reply;
        status_t result;
-       
+
        // Build and send the message, read the reply
        if (!err)
                err = msg.AddString("type", Type());
-       if (!err) 
+       if (!err)
                err = msg.AddInt32("which", B_REG_MIME_APP_HINT);
        if (!err && ref)
                err = msg.AddRef("app hint", ref);
-       if (!err) 
+       if (!err)
                err = BRoster::Private().SendTo(&msg, &reply, true);
        if (!err)
-               err = reply.what == B_REG_RESULT ? (status_t)B_OK : 
(status_t)B_BAD_REPLY;
+               err = (status_t)(reply.what == B_REG_RESULT ? B_OK : 
B_BAD_REPLY);
        if (!err)
                err = reply.FindInt32("result", &result);
        if (!err) 
-               err = result;   
-       return err;     
+               err = result;
+
+       return err;
 }
 
 
-/*! \brief Fetches the large or mini icon used by an application of this type 
for files of the
-       given type.
-       
-       This can be confusing, so here's how this function is intended to be 
used:
-       - The actual \c BMimeType object should be set to the MIME signature of 
an
-         application for whom you want to look up custom icons for custom MIME 
types.
-       - The \c type parameter specifies the file type whose custom icon you 
are fetching.
-       
-       The type of the \c BMimeType object is not required to actually be a 
subtype of
-       \c "application/"; that is the intended use however, and calling \c 
GetIconForType()
-       on a non-application type will likely return \c B_ENTRY_NOT_FOUND.
-       
-       The icon is copied into the \c BBitmap pointed to by \c icon. The 
bitmap must
-       be the proper size: \c 32x32 for the large icon, \c 16x16 for the mini 
icon.    
-       Additionally, the bitmap must be in the \c B_CMAP8 color space (8-bit 
color).
-       
-       \param type Pointer to a pre-allocated string containing the MIME type 
whose
-                   custom icon you wish to fetch.
-       \param icon Pointer to a pre-allocated \c BBitmap of proper size and 
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
-       - other error code: Failure     
-
-*/
+// Fetches the large or mini icon used by an application of this type for
+// files of the given type.
 status_t
 BMimeType::GetIconForType(const char *type, BBitmap *icon, icon_size which) 
const
 {
@@ -1266,27 +754,13 @@ BMimeType::GetIconForType(const char *type, BBitmap 
*icon, icon_size which) cons
                        err = get_icon_for_type(Type(), type, icon, which);
        } else
                err = GetIcon(icon, which);
+
        return err;
 }
 
 
-/*! \brief Fetches the vector icon used by an application of this type for 
files of
-       the given type.
-
-       The icon data is returned in \c data.
-       See the other GetIconForType() for more information.
-
-       \param type Pointer to a pre-allocated string containing the MIME type 
whose
-                   custom icon you wish to fetch.
-       \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.
-       \return
-       - \c B_OK: Success
-       - \c B_ENTRY_NOT_FOUND: No icon of the given size exists for the given 
type
-       - other error code: Failure     
-

[ *** diff truncated: 687 lines dropped *** ]



Other related posts:

  • » [haiku-commits] haiku: hrev43874 - src/kits/storage docs/user/storage - jscipione