Document roomlistmodel

src/models/roomlistmodel.cpp

@@ -69,6 +69,11 @@ RoomListModel::RoomListModel(QObject *parent)
 
 RoomListModel::~RoomListModel() = default;
 
+Quotient::Connection *RoomListModel::connection() const
+{
+    return m_connection;
+}
+
 void RoomListModel::setConnection(Connection *connection)
 {
     if (connection == m_connection) {
@@ -237,6 +242,11 @@ void RoomListModel::handleNotifications()
 }
 #endif
 
+int RoomListModel::notificationCount() const
+{
+    return m_notificationCount;
+}
+
 void RoomListModel::refreshNotificationCount()
 {
     int count = 0;
@@ -440,40 +450,40 @@ QHash<int, QByteArray> RoomListModel::roleNames() const
     return roles;
 }
 
-QString RoomListModel::categoryName(int section)
+QString RoomListModel::categoryName(int category)
 {
-    switch (section) {
+    switch (category) {
-    case 1:
+    case NeoChatRoomType::Invited:
         return i18n("Invited");
-    case 2:
+    case NeoChatRoomType::Favorite:
         return i18n("Favorite");
-    case 3:
+    case NeoChatRoomType::Direct:
         return i18n("Direct Messages");
-    case 4:
+    case NeoChatRoomType::Normal:
         return i18n("Normal");
-    case 5:
+    case NeoChatRoomType::Deprioritized:
         return i18n("Low priority");
-    case 6:
+    case NeoChatRoomType::Space:
         return i18n("Spaces");
     default:
         return "Deadbeef";
     }
 }
 
-QString RoomListModel::categoryIconName(int section)
+QString RoomListModel::categoryIconName(int category)
 {
-    switch (section) {
+    switch (category) {
-    case 1:
+    case NeoChatRoomType::Invited:
         return QStringLiteral("user-invisible");
-    case 2:
+    case NeoChatRoomType::Favorite:
         return QStringLiteral("favorite");
-    case 3:
+    case NeoChatRoomType::Direct:
         return QStringLiteral("dialog-messages");
-    case 4:
+    case NeoChatRoomType::Normal:
         return QStringLiteral("group");
-    case 5:
+    case NeoChatRoomType::Deprioritized:
         return QStringLiteral("object-order-lower");
-    case 6:
+    case NeoChatRoomType::Space:
         return QStringLiteral("group");
     default:
         return QStringLiteral("tools-report-bug");
@@ -511,7 +521,7 @@ NeoChatRoom *RoomListModel::roomByAliasOrId(const QString &aliasOrId)
     return nullptr;
 }
 
-int RoomListModel::indexForRoom(NeoChatRoom *room) const
+int RoomListModel::rowForRoom(NeoChatRoom *room) const
 {
     return m_rooms.indexOf(room);
 }

src/models/roomlistmodel.h

@@ -20,77 +20,137 @@ class NeoChatRoomType : public QObject
     Q_OBJECT
 
 public:
+    /**
+     * @brief Defines the room list categories a room can be assigned.
+     */
     enum Types {
-        Invited = 1,
+        Invited = 1, /**< The user has been invited to the room. */
-        Favorite,
+        Favorite, /**< The room is set as a favourite. */
-        Direct,
+        Direct, /**< The room is a direct chat. */
-        Normal,
+        Normal, /**< The default category for a joined room. */
-        Deprioritized,
+        Deprioritized, /**< The room is set as low priority. */
-        Space,
+        Space, /**< The room is a space. */
     };
     Q_ENUM(Types)
 };
 
+/**
+ * @class RoomListModel
+ *
+ * This class defines the model for visualising the user's list of joined rooms.
+ */
 class RoomListModel : public QAbstractListModel
 {
     Q_OBJECT
+
+    /**
+     * @brief The current connection that the model is getting its rooms from.
+     */
     Q_PROPERTY(Quotient::Connection *connection READ connection WRITE setConnection NOTIFY connectionChanged)
+
+    /**
+     * @brief The total number of notifications for all the rooms.
+     */
     Q_PROPERTY(int notificationCount READ notificationCount NOTIFY notificationCountChanged)
 
 public:
+    /**
+     * @brief Defines the model roles.
+     */
     enum EventRoles {
-        NameRole = Qt::UserRole + 1,
+        NameRole = Qt::UserRole + 1, /**< The name of the room. */
-        DisplayNameRole,
+        DisplayNameRole, /**< The display name of the room. */
-        AvatarRole,
+        AvatarRole, /**< The source URL for the room's avatar. */
-        CanonicalAliasRole,
+        CanonicalAliasRole, /**< The room canonical alias. */
-        TopicRole,
+        TopicRole, /**< The room topic. */
-        CategoryRole,
+        CategoryRole, /**< The room category, e.g favourite. */
-        UnreadCountRole,
+        UnreadCountRole, /**< The number of unread messages in the room. */
-        NotificationCountRole,
+        NotificationCountRole, /**< The number of notifications in the room. */
-        HighlightCountRole,
+        HighlightCountRole, /**< The number of highlighted messages in the room. */
-        LastEventRole,
+        LastEventRole, /**< Text for the last event in the room. */
-        LastActiveTimeRole,
+        LastActiveTimeRole, /**< The timestamp of the last event sent in the room. */
-        JoinStateRole,
+        JoinStateRole, /**< The local user's join state in the room. */
-        CurrentRoomRole,
+        CurrentRoomRole, /**< The room object for the room. */
-        CategoryVisibleRole,
+        CategoryVisibleRole, /**< If the room's category is visible. */
-        SubtitleTextRole,
+        SubtitleTextRole, /**< The text to show as the room subtitle. */
-        AvatarImageRole,
+        AvatarImageRole, /**< The room avatar as an image. */
-        IdRole,
+        IdRole, /**< The room matrix ID. */
-        IsSpaceRole,
+        IsSpaceRole, /**< Whether the room is a space. */
     };
     Q_ENUM(EventRoles)
 
     RoomListModel(QObject *parent = nullptr);
     ~RoomListModel() override;
 
-    [[nodiscard]] Quotient::Connection *connection() const
+    [[nodiscard]] Quotient::Connection *connection() const;
-    {
-        return m_connection;
-    }
     void setConnection(Quotient::Connection *connection);
-    void doResetModel();
 
-    Q_INVOKABLE [[nodiscard]] NeoChatRoom *roomAt(int row) const;
+    [[nodiscard]] int notificationCount() const;
 
+    /**
+     * @brief Get the given role value at the given index.
+     *
+     * @sa QAbstractItemModel::data
+     */
     [[nodiscard]] QVariant data(const QModelIndex &index, int role = Qt::DisplayRole) const override;
+
+    /**
+     * @brief Number of rows in the model.
+     *
+     * @sa QAbstractItemModel::rowCount
+     */
     Q_INVOKABLE [[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;
 
-    Q_INVOKABLE [[nodiscard]] static QString categoryName(int section);
+    /**
-    Q_INVOKABLE [[nodiscard]] static QString categoryIconName(int section);
+     * @brief Return the room at the given row.
+     */
+    Q_INVOKABLE [[nodiscard]] NeoChatRoom *roomAt(int row) const;
+
+    /**
+     * @brief Return a string to represent the given room category.
+     */
+    Q_INVOKABLE [[nodiscard]] static QString categoryName(int category);
+
+    /**
+     * @brief Return a string with the name of the given room category icon.
+     */
+    Q_INVOKABLE [[nodiscard]] static QString categoryIconName(int category);
+
+    /**
+     * @brief Set whether a given category should be visible or not.
+     *
+     * @param category the NeoChatRoomType::Types value for the category (it's an
+     *                 int due to the pain of Q_INVOKABLES and cpp enums).
+     * @param visible true if the category should be visible, false if not.
+     */
     Q_INVOKABLE void setCategoryVisible(int category, bool visible);
+
+    /**
+     * @brief Return whether a room category is set to be visible.
+     */
     Q_INVOKABLE [[nodiscard]] bool categoryVisible(int category) const;
-    Q_INVOKABLE [[nodiscard]] int indexForRoom(NeoChatRoom *room) const;
 
-    [[nodiscard]] int notificationCount() const
+    /**
-    {
+     * @brief Return the model row for the given room.
-        return m_notificationCount;
+     */
-    }
+    Q_INVOKABLE [[nodiscard]] int rowForRoom(NeoChatRoom *room) const;
 
+    /**
+     * @brief Return a room for the given room alias or room matrix ID.
+     *
+     * The room must be in the model.
+     */
     Q_INVOKABLE NeoChatRoom *roomByAliasOrId(const QString &aliasOrId);
 
 private Q_SLOTS:
+    void doResetModel();
     void doAddRoom(Quotient::Room *room);
     void updateRoom(Quotient::Room *room, Quotient::Room *prev);
     void deleteRoom(Quotient::Room *room);

src/qml/Page/RoomList/Page.qml

@@ -58,7 +58,7 @@ Kirigami.ScrollablePage {
     Connections {
         target: RoomManager
         function onCurrentRoomChanged() {
-            itemSelection.setCurrentIndex(roomListModel.index(roomListModel.indexForRoom(RoomManager.currentRoom), 0), ItemSelectionModel.SelectCurrent)
+            itemSelection.setCurrentIndex(roomListModel.index(roomListModel.rowForRoom(RoomManager.currentRoom), 0), ItemSelectionModel.SelectCurrent)
         }
     }