Updated the documentation.

Added some of the missing licensing information.
Corrected types in QML documentation to QML types like string.
Corrected wrong function parameter profiles.
Marked declarative class as internal. Only their QML documentation
is part of the public API.
Also, exposed the debugging flags to QML.

Change-Id: I41fd8d93e60ba3a7860bca81211321cb46705821
Sanity-Review: Qt Sanity Bot <qt_sanity_bot@ovi.com>
Reviewed-by: David Faure <faure@kde.org>

11 files changed, 390 insertions, 80 deletions

diff --git a/src/imports/mimetypes/qdeclarativemimedatabase.cpp b/src/imports/mimetypes/qdeclarativemimedatabase.cpp
index c913fff..8edd0cb 100644
--- a/src/imports/mimetypes/qdeclarativemimedatabase.cpp
+++ b/src/imports/mimetypes/qdeclarativemimedatabase.cpp
@@ -60,19 +60,99 @@ extern bool isQMimeDatabaseDebuggingActivated;
 /*!
     \qmlclass MimeDatabase QDeclarativeMimeDatabase
     \brief The QML MimeDatabase element maintains a database of MIME types.
+
+    The MIME type database is provided by the freedesktop.org shared-mime-info
+    project. If the MIME type database cannot be found on the system, Qt
+    will use its own copy of it.
+
+    Applications which want to define custom MIME types need to install an
+    XML file into the locations searched for MIME definitions.
+    These locations can be queried with
+    QStandardPaths::locateAll(QStandardPaths::GenericDataLocation, QLatin1String("mime/packages"),
+    QStandardPaths::LocateDirectory);
+    On a typical Unix system, this will be /usr/share/mime/packages/, but it is also
+    possible to extend the list of directories by setting the environment variable
+    XDG_DATA_DIRS. For instance adding /opt/myapp/share to XDG_DATA_DIRS will result
+    in /opt/myapp/share/mime/packages/ being searched for MIME definitions.
+
+    Here is an example of MIME XML:
+    \code
+    <?xml version="1.0" encoding="UTF-8"?>
+    <mime-info xmlns="http://www.freedesktop.org/standards/shared-mime-info">
+      <mime-type type="application/vnd.nokia.qt.qmakeprofile">
+        <comment xml:lang="en">Qt qmake Profile</comment>
+        <glob pattern="*.pro" weight="50"/>
+      </mime-type>
+    </mime-info>
+    \endcode
+
+    For more details about the syntax of XML MIME definitions, including defining
+    "magic" in order to detect MIME types based on data as well, read the
+    Shared Mime Info specification at
+    http://standards.freedesktop.org/shared-mime-info-spec/shared-mime-info-spec-latest.html
+
+    On Unix systems, a binary cache is used for more performance. This cache is generated
+    by the command "update-mime-database path", where path would be /opt/myapp/share/mime
+    in the above example. Make sure to run this command when installing the MIME type
+    definition file.
+
+    The class is protected by a QMutex and can therefore be accessed by threads.
+
+    \sa QMimeType
  */
 
 // ------------------------------------------------------------------------------------------------
 
 /*!
+    \internal
     \class QDeclarativeMimeDatabase
     \brief The QDeclarativeMimeDatabase class is the QML wrapper for the class QMimeDatabase which maintains a database of MIME types.
     \inherits QObject
+
+    The MIME type database is provided by the freedesktop.org shared-mime-info
+    project. If the MIME type database cannot be found on the system, Qt
+    will use its own copy of it.
+
+    Applications which want to define custom MIME types need to install an
+    XML file into the locations searched for MIME definitions.
+    These locations can be queried with
+    QStandardPaths::locateAll(QStandardPaths::GenericDataLocation, QLatin1String("mime/packages"),
+    QStandardPaths::LocateDirectory);
+    On a typical Unix system, this will be /usr/share/mime/packages/, but it is also
+    possible to extend the list of directories by setting the environment variable
+    XDG_DATA_DIRS. For instance adding /opt/myapp/share to XDG_DATA_DIRS will result
+    in /opt/myapp/share/mime/packages/ being searched for MIME definitions.
+
+    Here is an example of MIME XML:
+    \code
+    <?xml version="1.0" encoding="UTF-8"?>
+    <mime-info xmlns="http://www.freedesktop.org/standards/shared-mime-info">
+      <mime-type type="application/vnd.nokia.qt.qmakeprofile">
+        <comment xml:lang="en">Qt qmake Profile</comment>
+        <glob pattern="*.pro" weight="50"/>
+      </mime-type>
+    </mime-info>
+    \endcode
+
+    For more details about the syntax of XML MIME definitions, including defining
+    "magic" in order to detect MIME types based on data as well, read the
+    Shared Mime Info specification at
+    http://standards.freedesktop.org/shared-mime-info-spec/shared-mime-info-spec-latest.html
+
+    On Unix systems, a binary cache is used for more performance. This cache is generated
+    by the command "update-mime-database path", where path would be /opt/myapp/share/mime
+    in the above example. Make sure to run this command when installing the MIME type
+    definition file.
+
+    The class is protected by a QMutex and can therefore be accessed by threads.
+
+    \sa QMimeType
  */
 
 // ------------------------------------------------------------------------------------------------
 
 /*!
+    \internal
     \fn QDeclarativeMimeDatabase::QDeclarativeMimeDatabase(QObject *theParent);
     \brief Performs default initialization of the contained MimeDatabase, and attaches the object to the specified \a theParent for destruction.
  */
@@ -86,8 +166,9 @@ QDeclarativeMimeDatabase::QDeclarativeMimeDatabase(QObject *theParent) :
 // ------------------------------------------------------------------------------------------------
 
 /*!
+    \internal
     \fn QDeclarativeMimeDatabase::~QDeclarativeMimeDatabase();
-    \brief Destroys the the contained MimeDatabase.
+    \brief Destroys the contained MimeDatabase.
  */
 QDeclarativeMimeDatabase::~QDeclarativeMimeDatabase()
 {
@@ -97,6 +178,7 @@ QDeclarativeMimeDatabase::~QDeclarativeMimeDatabase()
 // ------------------------------------------------------------------------------------------------
 
 /*!
+    \internal
     \fn QMimeDatabase &QDeclarativeMimeDatabase::mimeDatabase()
     \brief Returns the contained MimeDatabase.
  */
@@ -108,8 +190,44 @@ QMimeDatabase &QDeclarativeMimeDatabase::mimeDatabase()
 // ------------------------------------------------------------------------------------------------
 
 /*!
-    \qmlproperty QVariantList MimeDatabase::mimeTypeNames
-    list of registered MIME types
+    \qmlproperty bool MimeDatabase::isDebuggingActivated
+    Holds the indication if debugging for the class is activated.
+ */
+
+// ------------------------------------------------------------------------------------------------
+
+/*!
+    \internal
+    \property QDeclarativeMimeDatabase::isDebuggingActivated
+    Holds the indication if debugging for the class is activated.
+ */
+
+// ------------------------------------------------------------------------------------------------
+
+bool QDeclarativeMimeDatabase::isDebuggingActivated() const
+{
+    return isQMimeDatabaseDebuggingActivated;
+}
+
+// ------------------------------------------------------------------------------------------------
+
+void QDeclarativeMimeDatabase::setIsDebuggingActivated(const bool newIsDebuggingActivated)
+{
+    isQMimeDatabaseDebuggingActivated = newIsDebuggingActivated;
+}
+
+// ------------------------------------------------------------------------------------------------
+
+/*!
+    \qmlproperty list<string> MimeDatabase::mimeTypeNames
+    Holds the list of registered MIME types.
+ */
+
+// ------------------------------------------------------------------------------------------------
+
+/*!
+    \property QDeclarativeMimeDatabase::mimeTypeNames
+    Holds the list of registered MIME types.
  */
 
 // ------------------------------------------------------------------------------------------------
@@ -134,13 +252,6 @@ QVariantList QDeclarativeMimeDatabase::mimeTypeNames() const
 
 // ------------------------------------------------------------------------------------------------
 
-/*!
-    \property QDeclarativeMimeDatabase::mimeTypeNames
-    \brief the list of registered MIME types
- */
-
-// ------------------------------------------------------------------------------------------------
-
 QDeclarativeMimeType *QDeclarativeMimeDatabase::mimeTypeForName (
                                                     const QString &nameOrAlias
                                                 )
diff --git a/src/imports/mimetypes/qdeclarativemimedatabase_p.h b/src/imports/mimetypes/qdeclarativemimedatabase_p.h
index 7d49fdf..861ae95 100644
--- a/src/imports/mimetypes/qdeclarativemimedatabase_p.h
+++ b/src/imports/mimetypes/qdeclarativemimedatabase_p.h
@@ -42,12 +42,10 @@
 #ifndef QDECLARATIVEMIMEDATABASE_P_H_INCLUDED
 #define QDECLARATIVEMIMEDATABASE_P_H_INCLUDED
 
+#include <QtCore/QObject>
 #include <qmimedatabase.h>
-
 #include <QtDeclarative/qdeclarative.h>
 
-#include <QtCore/QObject>
-
 class QDeclarativeMimeType;
 
 // ------------------------------------------------------------------------------------------------
@@ -60,6 +58,10 @@ class QDeclarativeMimeDatabase : public QObject
                READ mimeTypeNames
                STORED false)
 
+    Q_PROPERTY(bool isDebuggingActivated
+               READ isDebuggingActivated
+               WRITE setIsDebuggingActivated)
+
 protected:
     // We keep this destructor with its default value of 0 protected since
     // only QDeclarativePrivate::QDeclarativeElement<T> needs it:
@@ -70,6 +72,9 @@ public:
 
     QMimeDatabase &mimeDatabase();
 
+    bool isDebuggingActivated() const;
+    void setIsDebuggingActivated(bool newIsDebuggingActivated);
+
     QVariantList mimeTypeNames() const;
 
     Q_INVOKABLE QDeclarativeMimeType *mimeTypeForName (
diff --git a/src/imports/mimetypes/qdeclarativemimetype.cpp b/src/imports/mimetypes/qdeclarativemimetype.cpp
index 91dab97..aba0686 100644
--- a/src/imports/mimetypes/qdeclarativemimetype.cpp
+++ b/src/imports/mimetypes/qdeclarativemimetype.cpp
@@ -61,19 +61,55 @@ extern bool isQMimeTypeDebuggingActivated;
 /*!
     \qmlclass MimeType QDeclarativeMimeType
     \brief The QML MimeType element describes types of file or data, represented by a MIME type string.
+
+    For instance a file named "readme.txt" has the MIME type "text/plain".
+    The MIME type can be determined from the file name, or from the file
+    contents, or from both. MIME type determination can also be done on
+    buffers of data not coming from files.
+
+    Determining the MIME type of a file can be useful to make sure your
+    application supports it. It is also useful in file-manager-like applications
+    or widgets, in order to display an appropriate icon() for the file, or even
+    the descriptive comment() in detailed views.
+
+    To check if a file has the expected MIME type, you should use inherits()
+    rather than a simple string comparison based on the name(). This is because
+    MIME types can inherit from each other: for instance a C source file is
+    a specific type of plain text file, so text/x-csrc inherits text/plain.
+
+    \sa QMimeDatabase
  */
 
 // ------------------------------------------------------------------------------------------------
 
 /*!
+    \internal
     \class QDeclarativeMimeType
     \brief The QDeclarativeMimeType class is the QML wrapper for the class QMimeType which describes types of file or data, represented by a MIME type string.
     \inherits QObject
+
+    For instance a file named "readme.txt" has the MIME type "text/plain".
+    The MIME type can be determined from the file name, or from the file
+    contents, or from both. MIME type determination can also be done on
+    buffers of data not coming from files.
+
+    Determining the MIME type of a file can be useful to make sure your
+    application supports it. It is also useful in file-manager-like applications
+    or widgets, in order to display an appropriate icon() for the file, or even
+    the descriptive comment() in detailed views.
+
+    To check if a file has the expected MIME type, you should use inherits()
+    rather than a simple string comparison based on the name(). This is because
+    MIME types can inherit from each other: for instance a C source file is
+    a specific type of plain text file, so text/x-csrc inherits text/plain.
+
+    \sa QMimeDatabase
  */
 
 // ------------------------------------------------------------------------------------------------
 
 /*!
+    \internal
     \fn QDeclarativeMimeType::QDeclarativeMimeType(QObject *theParent);
     \brief Performs default initialization of the contained MimeType, and attaches the object to the specified \a theParent for destruction.
  */
@@ -94,6 +130,7 @@ QDeclarativeMimeType::QDeclarativeMimeType(QObject *theParent) :
 // ------------------------------------------------------------------------------------------------
 
 /*!
+    \internal
     \fn QDeclarativeMimeType::QDeclarativeMimeType(const QMimeType &other, QObject *theParent);
     \brief Copies the specified MimeType \a other, and attaches the object to the specified \a theParent for destruction.
  */
@@ -115,8 +152,9 @@ QDeclarativeMimeType::QDeclarativeMimeType(const QMimeType &other, QObject *theP
 
 #ifdef Q_COMPILER_RVALUE_REFS
 /*!
-    \fn QDeclarativeMimeType::QDeclarativeMimeType(const QMimeType &other, QObject *theParent);
-    \brief Moves the specified MimeType \a other, and attaches the object to the specified \a theParent for destruction.
+    \internal
+    \fn QDeclarativeMimeType::QDeclarativeMimeType(QMimeType &&other, QObject *theParent);
+    \brief Constructs this QDeclarativeMimeType object by moving the data of the QMimeType rvalue reference \a other, and attaches the object to the specified \a theParent for destruction.
  */
 QDeclarativeMimeType::QDeclarativeMimeType(QMimeType &&other, QObject *theParent) :
         QObject(theParent),
@@ -136,8 +174,9 @@ QDeclarativeMimeType::QDeclarativeMimeType(QMimeType &&other, QObject *theParent
 // ------------------------------------------------------------------------------------------------
 
 /*!
+    \internal
     \fn QDeclarativeMimeType::~QDeclarativeMimeType();
-    \brief Destroys the the contained MimeType.
+    \brief Destroys the contained MimeType.
  */
 QDeclarativeMimeType::~QDeclarativeMimeType()
 {
@@ -155,14 +194,14 @@ QDeclarativeMimeType::~QDeclarativeMimeType()
 
 /*!
     \qmlmethod void MimeType::assign(MimeType other)
-    Assigns from another object.
+    Assigns the data of \a other to this MimeType object.
  */
 
 // ------------------------------------------------------------------------------------------------
 
 /*!
     \fn void QDeclarativeMimeType::assign(QDeclarativeMimeType *other);
-    \brief Assigns from the object \a other.
+    \brief Assigns the data of \a other to this QDeclarativeMimeType object.
  */
 void QDeclarativeMimeType::assign(QDeclarativeMimeType *other)
 {
@@ -178,15 +217,17 @@ void QDeclarativeMimeType::assign(QDeclarativeMimeType *other)
 // ------------------------------------------------------------------------------------------------
 
 /*!
+    \internal
     \qmlmethod bool MimeType::equals(MimeType other)
-    Compares with the other object for equality.
+    Returns true if \a other equals this MimeType object, otherwise returns false.
  */
 
 // ------------------------------------------------------------------------------------------------
 
 /*!
+    \internal
     \fn bool QDeclarativeMimeType::equals(QDeclarativeMimeType *other) const;
-    \brief Returns if the \a other object has the same value.
+    \brief Returns true if \a other equals this QDeclarativeMimeType object, otherwise returns false.
  */
 bool QDeclarativeMimeType::equals(QDeclarativeMimeType *other) const
 {
@@ -205,10 +246,13 @@ bool QDeclarativeMimeType::equals(QDeclarativeMimeType *other) const
     Returns the properties as a JavaScript object.
  */
 
+// ------------------------------------------------------------------------------------------------
+
 #define ASSIGN_TO_PROPERTY(name) \
     result[#name] = name();
 
 /*!
+    \internal
     \fn QVariantMap QDeclarativeMimeType::properties() const;
     \brief Returns the properties as a JavaScript object.
  */
@@ -228,7 +272,7 @@ QVariantMap QDeclarativeMimeType::properties() const
 
 /*!
     \qmlmethod void MimeType::assignProperties(object other)
-    Assigns all properties from a JavaScript object.
+    Assigns the data of the JavaScript object \a other to this MimeType object.
  */
 
 // ------------------------------------------------------------------------------------------------
@@ -249,8 +293,9 @@ QVariantMap QDeclarativeMimeType::properties() const
     }
 
 /*!
+    \internal
     \fn void QDeclarativeMimeType::assignProperties(const QVariantMap &other);
-    \brief Assigns all properties from the JavaScript object \a other.
+    \brief Assigns the data of the QVariantMap \a other to this QDeclarativeMimeType object.
  */
 void QDeclarativeMimeType::assignProperties(const QVariantMap &other)
 {
@@ -267,7 +312,7 @@ void QDeclarativeMimeType::assignProperties(const QVariantMap &other)
 
 /*!
     \qmlmethod bool MimeType::equalsProperties(object other)
-    Compares if the properties of the specified JavaScript object are equal.
+    Returns true if the properties of the JavaScript object \a other equal the properties of this MimeType object, otherwise returns false.
  */
 
 // ------------------------------------------------------------------------------------------------
@@ -294,8 +339,9 @@ void QDeclarativeMimeType::assignProperties(const QVariantMap &other)
     }
 
 /*!
+    \internal
     \fn bool QDeclarativeMimeType::equalsProperties(const QVariantMap &other) const;
-    \brief Returns if the properties of the specified JavaScript object \a other are equal.
+    \brief Returns true if the properties of the JavaScript object \a other equal the properties of this QDeclarativeMimeType object, otherwise returns false.
  */
 bool QDeclarativeMimeType::equalsProperties(const QVariantMap &other) const
 {
@@ -312,6 +358,7 @@ bool QDeclarativeMimeType::equalsProperties(const QVariantMap &other) const
 // ------------------------------------------------------------------------------------------------
 
 /*!
+    \internal
     \fn QMimeType QDeclarativeMimeType::mimeType() const;
     \brief Returns the contained MimeType.
  */
@@ -323,8 +370,16 @@ QMimeType QDeclarativeMimeType::mimeType() const
 // ------------------------------------------------------------------------------------------------
 
 /*!
+    \qmlproperty bool MimeType::isValid
+    Holds the indication if the object contains valid data.
+ */
+
+// ------------------------------------------------------------------------------------------------
+
+/*!
+    \internal
     \property QDeclarativeMimeType::isValid
-    \brief the indication if the object contains valid data.
+    Holds the indication if the object contains valid data.
  */
 
 // ------------------------------------------------------------------------------------------------
@@ -336,6 +391,35 @@ bool QDeclarativeMimeType::isValid() const
 
 // ------------------------------------------------------------------------------------------------
 
+/*!
+    \qmlproperty bool MimeType::isDebuggingActivated
+    Holds the indication if debugging for the class is activated.
+ */
+
+// ------------------------------------------------------------------------------------------------
+
+/*!
+    \internal
+    \property QDeclarativeMimeType::isDebuggingActivated
+    Holds the indication if debugging for the class is activated.
+ */
+
+// ------------------------------------------------------------------------------------------------
+
+bool QDeclarativeMimeType::isDebuggingActivated() const
+{
+    return isQMimeTypeDebuggingActivated;
+}
+
+// ------------------------------------------------------------------------------------------------
+
+void QDeclarativeMimeType::setIsDebuggingActivated(const bool newIsDebuggingActivated)
+{
+    isQMimeTypeDebuggingActivated = newIsDebuggingActivated;
+}
+
+// ------------------------------------------------------------------------------------------------
+
 #ifndef Q_COMPILER_RVALUE_REFS
 QMIMETYPE_BUILDER
 #else
@@ -345,15 +429,16 @@ QMIMETYPE_BUILDER_FROM_RVALUE_REFS
 // ------------------------------------------------------------------------------------------------
 
 /*!
-    \qmlproperty QString MimeType::name
-    name of the MIME type
+    \qmlproperty string MimeType::name
+    Holds the name of the MIME type.
  */
 
 // ------------------------------------------------------------------------------------------------
 
 /*!
+    \internal
     \property QDeclarativeMimeType::name
-    \brief the name of the MIME type
+    Holds the name of the MIME type.
  */
 
 // ------------------------------------------------------------------------------------------------
@@ -432,15 +517,16 @@ void QDeclarativeMimeType::setComment(const QString &newComment)
 #endif
 
 /*!
-    \qmlproperty QString MimeType::genericIconName
-    file name of an icon image that represents the MIME type
+    \qmlproperty string MimeType::genericIconName
+    Holds the file name of an icon image that represents the MIME type.
  */
 
 // ------------------------------------------------------------------------------------------------
 
 /*!
+    \internal
     \property QDeclarativeMimeType::genericIconName
-    \brief the file name of an icon image that represents the MIME type
+    Holds the file name of an icon image that represents the MIME type.
  */
 
 // ------------------------------------------------------------------------------------------------
@@ -464,15 +550,16 @@ void QDeclarativeMimeType::setGenericIconName(const QString &newGenericIconName)
 // ------------------------------------------------------------------------------------------------
 
 /*!
-    \qmlproperty QString MimeType::iconName
-    file name of an icon image that represents the MIME type
+    \qmlproperty string MimeType::iconName
+    Holds the file name of an icon image that represents the MIME type.
  */
 
 // ------------------------------------------------------------------------------------------------
 
 /*!
+    \internal
     \property QDeclarativeMimeType::iconName
-    \brief the file name of an icon image that represents the MIME type
+    Holds the file name of an icon image that represents the MIME type.
  */
 
 // ------------------------------------------------------------------------------------------------
@@ -496,15 +583,16 @@ void QDeclarativeMimeType::setIconName(const QString &newIconName)
 // ------------------------------------------------------------------------------------------------
 
 /*!
-    \qmlproperty QVariantList MimeType::globPatterns
-    list of glob matching patterns
+    \qmlproperty list<string> MimeType::globPatterns
+    Holds the list of glob matching patterns.
  */
 
 // ------------------------------------------------------------------------------------------------
 
 /*!
+    \internal
     \property QDeclarativeMimeType::globPatterns
-    \brief the list of glob matching patterns
+    Holds the list of glob matching patterns.
  */
 
 // ------------------------------------------------------------------------------------------------
@@ -545,15 +633,16 @@ void QDeclarativeMimeType::setGlobPatterns(const QVariantList &newGlobPatterns)
 // ------------------------------------------------------------------------------------------------
 
 /*!
-    \qmlproperty QVariantList MimeType::suffixes
-    known suffixes for the MIME type
+    \qmlproperty list<string> MimeType::suffixes
+    Holds the known suffixes for the MIME type.
  */
 
 // ------------------------------------------------------------------------------------------------
 
 /*!
+    \internal
     \property QDeclarativeMimeType::suffixes
-    \brief the known suffixes for the MIME type
+    Holds the known suffixes for the MIME type.
  */
 
 // ------------------------------------------------------------------------------------------------
@@ -572,15 +661,16 @@ QVariantList QDeclarativeMimeType::suffixes() const
 // ------------------------------------------------------------------------------------------------
 
 /*!
-    \qmlproperty QString MimeType::preferredSuffix
-    preferred suffix for the MIME type
+    \qmlproperty string MimeType::preferredSuffix
+    Holds the preferred suffix for the MIME type.
  */
 
 // ------------------------------------------------------------------------------------------------
 
 /*!
+    \internal
     \property QDeclarativeMimeType::preferredSuffix
-    \brief the preferred suffix for the MIME type
+    Holds the preferred suffix for the MIME type.
  */
 
 // ------------------------------------------------------------------------------------------------
diff --git a/src/imports/mimetypes/qdeclarativemimetype_p.h b/src/imports/mimetypes/qdeclarativemimetype_p.h
index 3015c25..f643e2c 100644
--- a/src/imports/mimetypes/qdeclarativemimetype_p.h
+++ b/src/imports/mimetypes/qdeclarativemimetype_p.h
@@ -95,6 +95,10 @@ class QDeclarativeMimeType : public QObject
                READ isValid
                STORED false)
 
+    Q_PROPERTY(bool isDebuggingActivated
+               READ isDebuggingActivated
+               WRITE setIsDebuggingActivated)
+
 protected:
     // We keep this destructor with its default value of 0 protected since
     // only QDeclarativePrivate::QDeclarativeElement<T> needs it:
@@ -122,6 +126,9 @@ public:
 
     bool isValid() const;
 
+    bool isDebuggingActivated() const;
+    void setIsDebuggingActivated(bool newIsDebuggingActivated);
+
     QString name() const;
     void setName(const QString &newName);
 #if 0
diff --git a/src/mimetypes/qmimedatabase.cpp b/src/mimetypes/qmimedatabase.cpp
index e46a60f..9a91591 100644
--- a/src/mimetypes/qmimedatabase.cpp
+++ b/src/mimetypes/qmimedatabase.cpp
@@ -313,7 +313,7 @@ bool QMimeDatabasePrivate::inherits(const QString &mime, const QString &parent)
 
 /*!
     \fn QMimeDatabase::QMimeDatabase();
-    \brief Initializes the MIME database.
+    \brief Constructs this QMimeDatabase object.
  */
 QMimeDatabase::QMimeDatabase() :
         d(staticQMimeDatabase())
@@ -325,7 +325,7 @@ QMimeDatabase::QMimeDatabase() :
 
 /*!
     \fn QMimeDatabase::~QMimeDatabase();
-    \brief Resets the d pointer.
+    \brief Destroys the QMimeDatabase object, and resets the d pointer.
  */
 QMimeDatabase::~QMimeDatabase()
 {
diff --git a/src/mimetypes/qmimedatabase.h b/src/mimetypes/qmimedatabase.h
index 7b3e0ba..ad1aefc 100644
--- a/src/mimetypes/qmimedatabase.h
+++ b/src/mimetypes/qmimedatabase.h
@@ -27,6 +27,8 @@
 
 #include <QtCore/QStringList>
 
+// ------------------------------------------------------------------------------------------------
+
 QT_BEGIN_NAMESPACE
 
 class QByteArray;
diff --git a/src/mimetypes/qmimetype.cpp b/src/mimetypes/qmimetype.cpp
index 088db7a..604e956 100644
--- a/src/mimetypes/qmimetype.cpp
+++ b/src/mimetypes/qmimetype.cpp
@@ -31,6 +31,8 @@
 
 QT_BEGIN_NAMESPACE
 
+// ------------------------------------------------------------------------------------------------
+
 bool isQMimeTypeDebuggingActivated (false);
 
 #ifndef QT_NO_DEBUG_OUTPUT
@@ -39,9 +41,19 @@ bool isQMimeTypeDebuggingActivated (false);
 #define DBG() if (0) qDebug() << static_cast<const void *>(this) << Q_FUNC_INFO
 #endif
 
+// ------------------------------------------------------------------------------------------------
+
 QMimeTypePrivate::QMimeTypePrivate()
+        : name()
+        //, comment()
+        , localeComments()
+        , genericIconName()
+        , iconName()
+        , globPatterns()
 {}
 
+// ------------------------------------------------------------------------------------------------
+
 QMimeTypePrivate::QMimeTypePrivate(const QMimeType &other)
         : name(other.d->name)
         //, comment(other.d->comment)
@@ -51,6 +63,8 @@ QMimeTypePrivate::QMimeTypePrivate(const QMimeType &other)
         , globPatterns(other.d->globPatterns)
 {}
 
+// ------------------------------------------------------------------------------------------------
+
 void QMimeTypePrivate::clear()
 {
     name.clear();
@@ -61,9 +75,11 @@ void QMimeTypePrivate::clear()
     globPatterns.clear();
 }
 
+// ------------------------------------------------------------------------------------------------
+
 /*!
     \fn bool QMimeTypePrivate::operator==(const QMimeTypePrivate &other) const;
-    \brief Returns if the \a other object has the same value.
+    \brief Returns true if \a other equals this QMimeTypePrivate object, otherwise returns false.
  */
 bool QMimeTypePrivate::operator==(const QMimeTypePrivate &other) const
 {
@@ -76,6 +92,7 @@ bool QMimeTypePrivate::operator==(const QMimeTypePrivate &other) const
             globPatterns == other.globPatterns) {
         return true;
     }
+
     DBG() << name << other.name << (name == other.name);
     //DBG() << comment << other.comment << (comment == other.comment);
     DBG() << localeComments << other.localeComments << (localeComments == other.localeComments);
@@ -85,14 +102,17 @@ bool QMimeTypePrivate::operator==(const QMimeTypePrivate &other) const
     return false;
 }
 
+// ------------------------------------------------------------------------------------------------
+
 void QMimeTypePrivate::addGlobPattern(const QString &pattern)
 {
     globPatterns.append(pattern);
 }
 
+// ------------------------------------------------------------------------------------------------
+
 /*!
     \class QMimeType
-
     \brief The QMimeType class describes types of file or data, represented by a MIME type string.
 
     For instance a file named "readme.txt" has the MIME type "text/plain".
@@ -113,9 +133,11 @@ void QMimeTypePrivate::addGlobPattern(const QString &pattern)
     \sa QMimeDatabase
  */
 
+// ------------------------------------------------------------------------------------------------
+
 /*!
     \fn QMimeType::QMimeType();
-    \brief Initializes the attributes with default values that indicate an invalid MIME type.
+    \brief Constructs this QMimeType object initialized with default property values that indicate an invalid MIME type.
  */
 QMimeType::QMimeType() :
         d(new QMimeTypePrivate())
@@ -130,10 +152,11 @@ QMimeType::QMimeType() :
     DBG() << "preferredSuffix():" << preferredSuffix();
 }
 
+// ------------------------------------------------------------------------------------------------
+
 /*!
     \fn QMimeType::QMimeType(const QMimeType &other);
-    \brief Initializes the attributes with the data of another MIME type.
-    \a other The other MIME type the data of which is copied
+    \brief Constructs this QMimeType object as a copy of \a other.
  */
 QMimeType::QMimeType(const QMimeType &other) :
         d(other.d)
@@ -148,11 +171,12 @@ QMimeType::QMimeType(const QMimeType &other) :
     DBG() << "preferredSuffix():" << preferredSuffix();
 }
 
+// ------------------------------------------------------------------------------------------------
+
 #if !defined(Q_COMPILER_RVALUE_REFS) || TEST_COMPILER_RVALUE_REFS == 0
 /*!
     \fn QMimeType &QMimeType::operator=(const QMimeType &other);
-    \brief Assigns the data of another MIME type.
-    \a other The other MIME type the data of which is assigned
+    \brief Assigns the data of \a other to this QMimeType object, and returns a reference to this object.
  */
 QMimeType &QMimeType::operator=(const QMimeType &other)
 {
@@ -162,11 +186,12 @@ QMimeType &QMimeType::operator=(const QMimeType &other)
 }
 #endif
 
+// ------------------------------------------------------------------------------------------------
+
 #ifdef Q_COMPILER_RVALUE_REFS
 /*!
     \fn QMimeType::QMimeType(QMimeType &&other);
-    \brief Moves the data of another rvalue MIME type into the attributes.
-    \a other The other rvalue MIME type the data of which is moved
+    \brief Constructs this QMimeType object by moving the data of the rvalue reference \a other.
  */
 QMimeType::QMimeType(QMimeType &&other) :
         d(std::move(other.d))
@@ -182,10 +207,11 @@ QMimeType::QMimeType(QMimeType &&other) :
 }
 #endif
 
+// ------------------------------------------------------------------------------------------------
+
 /*!
     \fn QMimeType::QMimeType(const QMimeTypePrivate &dd);
-    \brief Assigns the data of a private MIME type object.
-    \a dd The private MIME typeobject the data of which is assigned
+    \brief Assigns the data of the QMimeTypePrivate \a dd to this QMimeType object, and returns a reference to this object.
  */
 QMimeType::QMimeType(const QMimeTypePrivate &dd) :
         d(new QMimeTypePrivate(dd))
@@ -200,10 +226,13 @@ QMimeType::QMimeType(const QMimeTypePrivate &dd) :
     DBG() << "preferredSuffix():" << preferredSuffix();
 }
 
+// ------------------------------------------------------------------------------------------------
+
 /*!
     \fn void QMimeType::swap(QMimeType &other);
-    \brief Swaps the properties of a MIME type with the properties of another MIME type.
-    \a other The other value MIME type the data of which is to be swapped with.
+    \brief Swaps QMimeType \a other with this QMimeType object.
+
+    This operation is very fast and never fails.
 
     The swap() method helps with the implementation of assignment
     operators in an exception-safe way. For more information consult
@@ -211,9 +240,11 @@ QMimeType::QMimeType(const QMimeTypePrivate &dd) :
     {More C++ Idioms - Copy-and-swap}.
  */
 
+// ------------------------------------------------------------------------------------------------
+
 /*!
     \fn QMimeType::~QMimeType();
-    \brief Releases the d pointer.
+    \brief Destroys the QMimeType object, and releases the d pointer.
  */
 QMimeType::~QMimeType()
 {
@@ -227,27 +258,29 @@ QMimeType::~QMimeType()
     DBG() << "preferredSuffix():" << preferredSuffix();
 }
 
+// ------------------------------------------------------------------------------------------------
+
 /*!
     \fn bool QMimeType::operator==(const QMimeType &other) const;
-    \brief Tests for equality with another MIME type.
-    \a other The other MIME type that is to be compared with
-    Returns if the other MIME type is equal.
+    \brief Returns true if \a other equals this QMimeType object, otherwise returns false.
  */
 bool QMimeType::operator==(const QMimeType &other) const
 {
     return d == other.d || *d == *other.d;
 }
 
+// ------------------------------------------------------------------------------------------------
+
 /*!
     \fn bool QMimeType::operator!=(const QMimeType &other) const;
-    \brief Tests for non-equality with another MIME type.
-    \a other The other MIME type that is to be compared with
-    Returns if the other MIME type is not equal.
+    \brief Returns true if \a other does not equal this QMimeType object, otherwise returns false.
  */
 
+// ------------------------------------------------------------------------------------------------
+
 /*!
     \fn bool QMimeType::isValid() const;
-    \brief Returns true if the MIME type is valid, otherwise returns false.
+    \brief Returns true if the QMimeType object contains valid data, otherwise returns false.
     A valid MIME type has a non-empty name().
     The invalid MIME type is the default-constructed QMimeType.
  */
@@ -256,6 +289,8 @@ bool QMimeType::isValid() const
     return !d->name.isEmpty();
 }
 
+// ------------------------------------------------------------------------------------------------
+
 /*!
     \fn bool QMimeType::isDefault() const;
     Returns true if this MIME type is the default MIME type which
@@ -266,6 +301,8 @@ bool QMimeType::isDefault() const
     return d->name == QMimeDatabasePrivate::instance()->defaultMimeType();
 }
 
+// ------------------------------------------------------------------------------------------------
+
 /*!
     \fn QString QMimeType::name() const;
     \brief Returns the name of the MIME type.
@@ -275,6 +312,8 @@ QString QMimeType::name() const
     return d->name;
 }
 
+// ------------------------------------------------------------------------------------------------
+
 #if 0
 /*!
     \fn QStringList QMimeType::aliases() const;
@@ -287,6 +326,8 @@ QStringList QMimeType::aliases() const
 }
 #endif
 
+// ------------------------------------------------------------------------------------------------
+
 /*!
     \fn QString QMimeType::comment(const QString& localeName) const;
     \brief Returns the description of the MIME type to be displayed on user interfaces.
@@ -323,6 +364,8 @@ QString QMimeType::comment(const QString& localeName) const
     return d->name;
 }
 
+// ------------------------------------------------------------------------------------------------
+
 /*!
     \fn QString QMimeType::genericIconName() const;
     \brief Returns the file name of a generic icon that represents the MIME type.
@@ -352,6 +395,8 @@ QString QMimeType::genericIconName() const
     return d->genericIconName;
 }
 
+// ------------------------------------------------------------------------------------------------
+
 /*!
     \fn QString QMimeType::iconName() const;
     \brief Returns the file name of an icon image that represents the MIME type.
@@ -371,6 +416,8 @@ QString QMimeType::iconName() const
     return d->iconName;
 }
 
+// ------------------------------------------------------------------------------------------------
+
 /*!
     \fn QStringList QMimeType::globPatterns() const;
     \brief Returns the list of glob matching patterns.
@@ -381,6 +428,8 @@ QStringList QMimeType::globPatterns() const
     return d->globPatterns;
 }
 
+// ------------------------------------------------------------------------------------------------
+
 /*!
     A type is a subclass of another type if any instance of the first type is
     also an instance of the second. For example, all image/svg+xml files are also
@@ -398,6 +447,8 @@ QStringList QMimeType::parentMimeTypes() const
     return QMimeDatabasePrivate::instance()->provider()->parents(d->name);
 }
 
+// ------------------------------------------------------------------------------------------------
+
 static void collectParentMimeTypes(const QString& mime, QStringList& allParents)
 {
     QStringList parents = QMimeDatabasePrivate::instance()->provider()->parents(mime);
@@ -413,6 +464,8 @@ static void collectParentMimeTypes(const QString& mime, QStringList& allParents)
     }
 }
 
+// ------------------------------------------------------------------------------------------------
+
 /*!
     Return all the parent mimetypes of this mimetype, direct and indirect.
     This includes the parent(s) of its parent(s), etc.
@@ -430,6 +483,8 @@ QStringList QMimeType::allParentMimeTypes() const
     return allParents;
 }
 
+// ------------------------------------------------------------------------------------------------
+
 /*!
     \fn QStringList QMimeType::suffixes() const;
     \brief Returns the known suffixes for the MIME type.
@@ -452,6 +507,8 @@ QStringList QMimeType::suffixes() const
     return result;
 }
 
+// ------------------------------------------------------------------------------------------------
+
 /*!
     \fn QString QMimeType::preferredSuffix() const;
     \brief Returns the preferred suffix for the MIME type.
@@ -462,6 +519,8 @@ QString QMimeType::preferredSuffix() const
     return suffixList.isEmpty() ? QString() : suffixList.at(0);
 }
 
+// ------------------------------------------------------------------------------------------------
+
 /*!
     \fn QString QMimeType::filterString() const;
     Returns a filter string usable for a file dialog.
@@ -484,6 +543,8 @@ QString QMimeType::filterString() const
     return filter;
 }
 
+// ------------------------------------------------------------------------------------------------
+
 /*!
     \fn bool QMimeType::inherits(const QString &mimeTypeName) const;
     Returns true if this mimetype is \a mimeTypeName,
@@ -497,6 +558,8 @@ bool QMimeType::inherits(const QString &mimeTypeName) const
     return QMimeDatabasePrivate::instance()->inherits(d->name, mimeTypeName);
 }
 
+// ------------------------------------------------------------------------------------------------
+
 #undef DBG
 
 QT_END_NAMESPACE
diff --git a/src/mimetypes/qmimetype.h b/src/mimetypes/qmimetype.h
index 7fc6d4e..615479b 100644
--- a/src/mimetypes/qmimetype.h
+++ b/src/mimetypes/qmimetype.h
@@ -31,6 +31,8 @@ QT_BEGIN_NAMESPACE struct QMimeTypePrivate; QT_END_NAMESPACE
 QT_BEGIN_NAMESPACE class QFileinfo; QT_END_NAMESPACE
 QT_BEGIN_NAMESPACE class QStringList; QT_END_NAMESPACE
 
+// ------------------------------------------------------------------------------------------------
+
 QT_BEGIN_NAMESPACE
 
 class QMIME_EXPORT QMimeType
diff --git a/src/mimetypes/qmimetype_p.h b/src/mimetypes/qmimetype_p.h
index 405def1..e7b2cef 100644
--- a/src/mimetypes/qmimetype_p.h
+++ b/src/mimetypes/qmimetype_p.h
@@ -26,6 +26,8 @@
 #include <QtCore/QHash>
 #include <QtCore/QStringList>
 
+// ------------------------------------------------------------------------------------------------
+
 QT_BEGIN_NAMESPACE
 
 struct QMIME_EXPORT QMimeTypePrivate : public QSharedData
@@ -54,6 +56,8 @@ struct QMIME_EXPORT QMimeTypePrivate : public QSharedData
 
 QT_END_NAMESPACE
 
+// ------------------------------------------------------------------------------------------------
+
 #define QMIMETYPE_BUILDER \
     QT_BEGIN_NAMESPACE \
     static QMimeType buildQMimeType ( \
diff --git a/tests/auto/qmimedatabase/tst_qmimedatabase.cpp b/tests/auto/qmimedatabase/tst_qmimedatabase.cpp
index 27a7374..8c8dc89 100644
--- a/tests/auto/qmimedatabase/tst_qmimedatabase.cpp
+++ b/tests/auto/qmimedatabase/tst_qmimedatabase.cpp
@@ -2,6 +2,39 @@
 **
 ** TODO Provide Licensing information
 **
+** This file is part of the QtMimeTypes addon of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:LGPL$
+** GNU Lesser General Public License Usage
+** This file may be used under the terms of the GNU Lesser General Public
+** License version 2.1 as published by the Free Software Foundation and
+** appearing in the file LICENSE.LGPL included in the packaging of this
+** file. Please review the following information to ensure the GNU Lesser
+** General Public License version 2.1 requirements will be met:
+** http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
+**
+** In addition, as a special exception, Nokia gives you certain additional
+** rights. These rights are described in the Nokia Qt LGPL Exception
+** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
+**
+** GNU General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU General
+** Public License version 3.0 as published by the Free Software Foundation
+** and appearing in the file LICENSE.GPL included in the packaging of this
+** file. Please review the following information to ensure the GNU General
+** Public License version 3.0 requirements will be met:
+** http://www.gnu.org/copyleft/gpl.html.
+**
+** Other Usage
+** Alternatively, this file may be used in accordance with the terms and
+** conditions contained in a signed written agreement between you and Nokia.
+**
+**
+**
+**
+**
+** $QT_END_LICENSE$
+**
 ****************************************************************************/
 
 #include "tst_qmimedatabase.h"
diff --git a/tests/auto/qmimetype/tst_qmimetype.cpp b/tests/auto/qmimetype/tst_qmimetype.cpp
index f1b4c19..d2e5eb6 100644
--- a/tests/auto/qmimetype/tst_qmimetype.cpp
+++ b/tests/auto/qmimetype/tst_qmimetype.cpp
@@ -60,11 +60,10 @@ void tst_qmimetype::initTestCase()
 
 static QString qMimeTypeName()
 {
-    return QString::fromLatin1("image/png");
+    static const QString result ("No name of the MIME type");
+    return result;
 }
 
-// ------------------------------------------------------------------------------------------------
-
 #if 0
 static QString qMimeTypeDisplayName()
 {
@@ -72,22 +71,18 @@ static QString qMimeTypeDisplayName()
 }
 #endif
 
-// ------------------------------------------------------------------------------------------------
-
 static QString qMimeTypeGenericIconName()
 {
-    return QString::fromLatin1("/usr/share/icons/oxygen/64x64/mimetypes/image-x-generic.png");
+    static const QString result ("No file name of an icon image that represents the MIME type");
+    return result;
 }
 
-// ------------------------------------------------------------------------------------------------
-
 static QString qMimeTypeIconName()
 {
-    return QString::fromLatin1("/usr/share/icons/oxygen/64x64/mimetypes/image-x.png");
+    static const QString result ("No file name of an icon image that represents the MIME type");
+    return result;
 }
 
-// ------------------------------------------------------------------------------------------------
-
 static QStringList buildQMimeTypeFilenameExtensions()
 {
     QStringList result;
@@ -95,8 +90,6 @@ static QStringList buildQMimeTypeFilenameExtensions()
     return result;
 }
 
-// ------------------------------------------------------------------------------------------------
-
 static QStringList qMimeTypeGlobPatterns()
 {
     static const QStringList result (buildQMimeTypeFilenameExtensions());
@@ -245,7 +238,7 @@ void tst_qmimetype::test_suffixes()
                   )
               );
 
-    // Verify that the FilenameExtensions are part of the equality test:
+    // Verify that the Suffixes are part of the equality test:
     QCOMPARE(instantiatedQMimeType.globPatterns(), qMimeTypeGlobPatterns());
     QCOMPARE(instantiatedQMimeType.suffixes(), QStringList() << QString::fromLatin1("png"));