Fix allParentMimeTypes including the starting mimetype. Added docu.

Change-Id: I8d238027df522555a7cadc573d713b34e0bab104
Sanity-Review: Qt Sanity Bot <qt_sanity_bot@ovi.com>
Reviewed-by: Wolf-Michael Bolle <wolf-michael.bolle@nokia.com>

2 files changed, 30 insertions, 5 deletions

diff --git a/src/mimetypes/qmimetype.cpp b/src/mimetypes/qmimetype.cpp
index 0cb5624..088db7a 100644
--- a/src/mimetypes/qmimetype.cpp
+++ b/src/mimetypes/qmimetype.cpp
@@ -332,6 +332,7 @@ QString QMimeType::comment(const QString& localeName) const
     or archives) that can use a common icon.
     The freedesktop.org Icon Naming Specification lists a set of such icon names.
 
+    The icon name can be given to QIcon::fromTheme() in order to load the icon.
  */
 QString QMimeType::genericIconName() const
 {
@@ -354,6 +355,8 @@ QString QMimeType::genericIconName() const
 /*!
     \fn QString QMimeType::iconName() const;
     \brief Returns the file name of an icon image that represents the MIME type.
+
+    The icon name can be given to QIcon::fromTheme() in order to load the icon.
  */
 QString QMimeType::iconName() const
 {
@@ -378,6 +381,18 @@ 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
+    text/xml, text/plain and application/octet-stream files. Subclassing is about
+    the format, rather than the category of the data (for example, there is no
+    'generic spreadsheet' class that all spreadsheets inherit from).
+    Conversely, the parent mimetype of image/svg+xml is text/xml.
+
+    A mimetype can have multiple parents. For instance application/x-perl
+    has two parents: application/x-executable and text/plain. This makes
+    it possible to both execute perl scripts, and to open them in text editors.
+*/
 QStringList QMimeType::parentMimeTypes() const
 {
     return QMimeDatabasePrivate::instance()->provider()->parents(d->name);
@@ -398,14 +413,20 @@ 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.
+
+    For instance, for image/svg+xml the list would be:
+    application/xml, text/plain, application/octet-stream.
+
+    Note that application/octet-stream is the ultimate parent for all types
+    of files (but not directories).
+*/
 QStringList QMimeType::allParentMimeTypes() const
 {
     QStringList allParents;
-    const QString canonical = d->name;
-    if (!canonical.isEmpty())
-        allParents.append(canonical);
     collectParentMimeTypes(d->name, allParents);
-
     return allParents;
 }
 
@@ -465,7 +486,8 @@ QString QMimeType::filterString() const
 
 /*!
     \fn bool QMimeType::inherits(const QString &mimeTypeName) const;
-    Returns true if this mimetype is \a mimeTypeName, or inherits \a mimeTypeName,
+    Returns true if this mimetype is \a mimeTypeName,
+    or inherits \a mimeTypeName (see parentMimeTypes()),
     or \a mimeTypeName is an alias for this mimetype.
  */
 bool QMimeType::inherits(const QString &mimeTypeName) const
diff --git a/tests/auto/qmimedatabase/tst_qmimedatabase.cpp b/tests/auto/qmimedatabase/tst_qmimedatabase.cpp
index 98334a6..27a7374 100644
--- a/tests/auto/qmimedatabase/tst_qmimedatabase.cpp
+++ b/tests/auto/qmimedatabase/tst_qmimedatabase.cpp
@@ -250,6 +250,9 @@ void tst_qmimedatabase::test_inheritance()
     // Must be least-specific last, i.e. breadth first.
     QCOMPARE(allShellParents.last(), QString::fromLatin1("application/octet-stream"));
 
+    const QStringList allSvgParents = db.mimeTypeForName(QString::fromLatin1("image/svg+xml")).allParentMimeTypes();
+    QCOMPARE(allSvgParents, QStringList() << QLatin1String("application/xml") << QLatin1String("text/plain") << QLatin1String("application/octet-stream"));
+
     // Check that text/x-mrml knows that it inherits from text/plain (implicitly)
     const QMimeType mrml = db.mimeTypeForName(QString::fromLatin1("text/x-mrml"));
     QVERIFY(mrml.isValid());