From a807cc6143ad54279fc46ade18ab1752cfa22f4e Mon Sep 17 00:00:00 2001
From: James Graham <james.h.graham@protonmail.com>
Date: Fri, 14 Apr 2023 12:57:05 +0000
Subject: [PATCH] Document customemojimodel

---
 src/models/customemojimodel.h | 55 ++++++++++++++++++++++++++++++-----
 1 file changed, 48 insertions(+), 7 deletions(-)

diff --git a/src/models/customemojimodel.h b/src/models/customemojimodel.h
index c758a7434..af75f0cbe 100644
--- a/src/models/customemojimodel.h
+++ b/src/models/customemojimodel.h
@@ -17,19 +17,29 @@ struct CustomEmoji {
     Q_PROPERTY(QString name MEMBER name)
 };
 
+/**
+ * @class CustomEmojiModel
+ *
+ * This class defines the model for custom user emojis.
+ *
+ * This is based upon the im.ponies.user_emotes spec (MSC2545).
+ */
 class CustomEmojiModel : public QAbstractListModel
 {
     Q_OBJECT
 
 public:
+    /**
+     * @brief Defines the model roles.
+     */
     enum Roles {
-        Name = Qt::DisplayRole,
-        ImageURL,
-        ModelData, // for emulating the regular emoji model's usage, otherwise the UI code would get too complicated
-        MxcUrl = 50,
-        DisplayRole = 51,
-        ReplacedTextRole = 52,
-        DescriptionRole = 53, // also invalid, reserved
+        Name = Qt::DisplayRole, /**< The name of the emoji. */
+        ImageURL, /**< The URL for the custom emoji. */
+        ModelData, /**< for emulating the regular emoji model's usage, otherwise the UI code would get too complicated. */
+        MxcUrl = 50, /**< The mxc source URL for the custom emoji. */
+        DisplayRole = 51, /**< The name of the emoji. For compatibility with EmojiModel. */
+        ReplacedTextRole = 52, /**< The name of the emoji. For compatibility with EmojiModel. */
+        DescriptionRole = 53, /**< Invalid, reserved. For compatibility with EmojiModel. */
     };
     Q_ENUM(Roles);
 
@@ -39,14 +49,45 @@ public:
         return _instance;
     }
 
+    /**
+     * @brief Get the given role value at the given index.
+     *
+     * @sa QAbstractItemModel::data
+     */
     QVariant data(const QModelIndex &idx, int role = Qt::DisplayRole) const override;
+
+    /**
+     * @brief Number of rows in the model.
+     *
+     * @sa  QAbstractItemModel::rowCount
+     */
     int rowCount(const QModelIndex &parent = QModelIndex()) const override;
 
+    /**
+     * @brief Returns a mapping from Role enum values to role names.
+     *
+     * @sa Roles, QAbstractItemModel::roleNames()
+     */
     QHash<int, QByteArray> roleNames() const override;
 
+    /**
+     * @brief Substitute any custom emojis for an image in the input text.
+     */
     Q_INVOKABLE QString preprocessText(const QString &it);
+
+    /**
+     * @brief Return a list of custom emojis where the name contains the filter text.
+     */
     Q_INVOKABLE QVariantList filterModel(const QString &filter);
+
+    /**
+     * @brief Add a new emoji to the model.
+     */
     Q_INVOKABLE void addEmoji(const QString &name, const QUrl &location);
+
+    /**
+     * @brief Remove an emoji from the model.
+     */
     Q_INVOKABLE void removeEmoji(const QString &name);
 
 private: