From 800194c6f5c19daec7d422051e83a5cf5c7815bb Mon Sep 17 00:00:00 2001
From: James Graham <james.h.graham@protonmail.com>
Date: Sat, 22 Apr 2023 08:34:22 +0000
Subject: [PATCH] Document userdirectorylistmodel

---
 src/models/userdirectorylistmodel.cpp | 15 +++++
 src/models/userdirectorylistmodel.h   | 87 +++++++++++++++++++--------
 2 files changed, 76 insertions(+), 26 deletions(-)

diff --git a/src/models/userdirectorylistmodel.cpp b/src/models/userdirectorylistmodel.cpp
index 209c5e126..c4a7ac311 100644
--- a/src/models/userdirectorylistmodel.cpp
+++ b/src/models/userdirectorylistmodel.cpp
@@ -13,6 +13,11 @@ UserDirectoryListModel::UserDirectoryListModel(QObject *parent)
 {
 }
 
+Quotient::Connection *UserDirectoryListModel::connection() const
+{
+    return m_connection;
+}
+
 void UserDirectoryListModel::setConnection(Connection *conn)
 {
     if (m_connection == conn) {
@@ -42,6 +47,11 @@ void UserDirectoryListModel::setConnection(Connection *conn)
     Q_EMIT limitedChanged();
 }
 
+QString UserDirectoryListModel::keyword() const
+{
+    return m_keyword;
+}
+
 void UserDirectoryListModel::setKeyword(const QString &value)
 {
     if (m_keyword == value) {
@@ -62,6 +72,11 @@ void UserDirectoryListModel::setKeyword(const QString &value)
     Q_EMIT limitedChanged();
 }
 
+bool UserDirectoryListModel::limited() const
+{
+    return m_limited;
+}
+
 void UserDirectoryListModel::search(int count)
 {
     if (count < 1) {
diff --git a/src/models/userdirectorylistmodel.h b/src/models/userdirectorylistmodel.h
index ade621aec..05d28c03c 100644
--- a/src/models/userdirectorylistmodel.h
+++ b/src/models/userdirectorylistmodel.h
@@ -13,47 +13,87 @@ namespace Quotient
 class Connection;
 }
 
+/**
+ * @class UserDirectoryListModel
+ *
+ * This class defines the model for visualising the results of a user search.
+ *
+ * The model searches for users that have the given keyword in the matrix
+ * ID or the display name. See
+ * https://spec.matrix.org/v1.6/client-server-api/#post_matrixclientv3user_directorysearch
+ * for more info on matrix user searches.
+ */
 class UserDirectoryListModel : public QAbstractListModel
 {
     Q_OBJECT
+
+    /**
+     * @brief The current connection that the model is getting users from.
+     */
     Q_PROPERTY(Quotient::Connection *connection READ connection WRITE setConnection NOTIFY connectionChanged)
+
+    /**
+     * @brief The keyword to use in the search.
+     */
     Q_PROPERTY(QString keyword READ keyword WRITE setKeyword NOTIFY keywordChanged)
+
+    /**
+     * @brief Whether the current results have been truncated.
+     */
     Q_PROPERTY(bool limited READ limited NOTIFY limitedChanged)
 
 public:
+    /**
+     * @brief Defines the model roles.
+     */
     enum EventRoles {
-        NameRole = Qt::DisplayRole + 1,
-        AvatarRole,
-        UserIDRole,
-        DirectChatsRole,
+        NameRole = Qt::DisplayRole + 1, /**< The user's display name. */
+        AvatarRole, /**< The source URL for the user's avatar. */
+        UserIDRole, /**< Matrix ID of the user. */
+        DirectChatsRole, /**< A list of direct chat matrix IDs with the user. */
     };
 
     UserDirectoryListModel(QObject *parent = nullptr);
 
-    [[nodiscard]] QVariant data(const QModelIndex &index, int role = NameRole) const override;
-    [[nodiscard]] int rowCount(const QModelIndex &parent = QModelIndex()) const override;
-
-    [[nodiscard]] QHash<int, QByteArray> roleNames() const override;
-
-    [[nodiscard]] Quotient::Connection *connection() const
-    {
-        return m_connection;
-    }
+    [[nodiscard]] Quotient::Connection *connection() const;
     void setConnection(Quotient::Connection *conn);
 
-    [[nodiscard]] QString keyword() const
-    {
-        return m_keyword;
-    }
+    [[nodiscard]] QString keyword() const;
     void setKeyword(const QString &value);
 
-    [[nodiscard]] bool limited() const
-    {
-        return m_limited;
-    }
+    [[nodiscard]] bool limited() const;
 
+    /**
+     * @brief Get the given role value at the given index.
+     *
+     * @sa QAbstractItemModel::data
+     */
+    [[nodiscard]] QVariant data(const QModelIndex &index, int role = NameRole) const override;
+
+    /**
+     * @brief Number of rows in the model.
+     *
+     * @sa QAbstractItemModel::rowCount
+     */
+    [[nodiscard]] int rowCount(const QModelIndex &parent = QModelIndex()) const override;
+
+    /**
+     * @brief Returns a mapping from Role enum values to role names.
+     *
+     * @sa EventRoles, QAbstractItemModel::roleNames()
+     */
+    [[nodiscard]] QHash<int, QByteArray> roleNames() const override;
+
+    /**
+     * @brief Start the user search.
+     */
     Q_INVOKABLE void search(int count = 50);
 
+Q_SIGNALS:
+    void connectionChanged();
+    void keywordChanged();
+    void limitedChanged();
+
 private:
     Quotient::Connection *m_connection = nullptr;
     QString m_keyword;
@@ -64,9 +104,4 @@ private:
     QVector<Quotient::SearchUserDirectoryJob::User> users;
 
     Quotient::SearchUserDirectoryJob *job = nullptr;
-
-Q_SIGNALS:
-    void connectionChanged();
-    void keywordChanged();
-    void limitedChanged();
 };