From af078f03d01881aa66d533a8bd68fc6372e8902d Mon Sep 17 00:00:00 2001
From: James Graham <james.h.graham@protonmail.com>
Date: Thu, 27 Apr 2023 15:20:36 +0000
Subject: [PATCH] Document filetypesingleton

---
 src/filetypesingleton.h | 77 +++++++++++++++++++++++++++++++++++++++--
 1 file changed, 75 insertions(+), 2 deletions(-)

diff --git a/src/filetypesingleton.h b/src/filetypesingleton.h
index 06519c1f6..4086bf34b 100644
--- a/src/filetypesingleton.h
+++ b/src/filetypesingleton.h
@@ -11,11 +11,31 @@
 
 class FileTypeSingletonPrivate;
 
+/**
+ * @class FileTypeSingleton
+ *
+ * Provide a singleton to expose the functionality of QMimeDatabase.
+ *
+ * @sa QMimeDatabase
+ */
 class FileTypeSingleton : public QObject
 {
     Q_OBJECT
+
+    /**
+     * @brief List of supported image formats.
+     *
+     * Returns a list of file extensions, not MIME types.
+     */
     Q_PROPERTY(QStringList supportedImageFormats READ supportedImageFormats CONSTANT FINAL)
+
+    /**
+     * @brief List of supported animated image formats.
+     *
+     * Returns a list of file extensions, not MIME types.
+     */
     Q_PROPERTY(QStringList supportedAnimatedImageFormats READ supportedAnimatedImageFormats CONSTANT FINAL)
+
     QML_NAMED_ELEMENT(FileType)
     QML_SINGLETON
 
@@ -23,26 +43,79 @@ public:
     explicit FileTypeSingleton(QObject *parent = nullptr);
     ~FileTypeSingleton();
 
-    // Most of the code in this public section was copy/pasted from qmimedatabase.h
+    /**
+     * @brief Returns a MIME type for nameOrAlias or an invalid one if none found.
+     *
+     * @sa QMimeDatabase
+     */
     Q_INVOKABLE QMimeType mimeTypeForName(const QString &nameOrAlias) const;
 
     enum MatchMode { MatchDefault, MatchExtension, MatchContent };
     Q_ENUM(MatchMode)
 
+    /**
+     * @brief Returns a MIME type for the file named fileName using mode.
+     *
+     * @sa QMimeDatabase
+     */
     Q_INVOKABLE QMimeType mimeTypeForFile(const QString &fileName, FileTypeSingleton::MatchMode mode = MatchDefault) const;
+
+    /**
+     * @brief Returns a MIME type for fileInfo.
+     *
+     * @sa QMimeDatabase
+     */
     Q_INVOKABLE QMimeType mimeTypeForFile(const QFileInfo &fileInfo, FileTypeSingleton::MatchMode mode = MatchDefault) const;
+
+    /**
+     * @brief Returns the MIME types for the file name fileName.
+     *
+     * @sa QMimeDatabase
+     */
     Q_INVOKABLE QList<QMimeType> mimeTypesForFileName(const QString &fileName) const;
 
+    /**
+     * @brief Returns a MIME type for data.
+     *
+     * @sa QMimeDatabase
+     */
     Q_INVOKABLE QMimeType mimeTypeForData(const QByteArray &data) const;
+
+    /**
+     * @brief Returns a MIME type for the data in device.
+     *
+     * @sa QMimeDatabase
+     */
     Q_INVOKABLE QMimeType mimeTypeForData(QIODevice *device) const;
 
+    /**
+     * @brief Returns a MIME type for url.
+     *
+     * @sa QMimeDatabase
+     */
     Q_INVOKABLE QMimeType mimeTypeForUrl(const QUrl &url) const;
+
+    /**
+     * @brief Returns a MIME type for the given fileName and device data.
+     *
+     * @sa QMimeDatabase
+     */
     Q_INVOKABLE QMimeType mimeTypeForFileNameAndData(const QString &fileName, QIODevice *device) const;
+
+    /**
+     * @brief Returns a MIME type for the given fileName and device data.
+     *
+     * @sa QMimeDatabase
+     */
     Q_INVOKABLE QMimeType mimeTypeForFileNameAndData(const QString &fileName, const QByteArray &data) const;
 
+    /**
+     * @brief Returns the suffix for the file fileName, as known by the MIME database.
+     *
+     * @sa QMimeDatabase
+     */
     Q_INVOKABLE QString suffixForFileName(const QString &fileName) const;
 
-    // These return a list of file extensions, not mimetypes
     QStringList supportedImageFormats() const;
     QStringList supportedAnimatedImageFormats() const;