Document completionproxymodel

src/models/completionproxymodel.cpp

@@ -2,9 +2,8 @@
 // SPDX-License-Identifier: LGPL-2.0-or-later
 
 #include "completionproxymodel.h"
-#include <QDebug>
 
-#include "neochatroom.h"
+#include <QDebug>
 
 bool CompletionProxyModel::filterAcceptsRow(int sourceRow, const QModelIndex &sourceParent) const
 {
@@ -44,7 +43,6 @@ int CompletionProxyModel::secondaryFilterRole() const
 void CompletionProxyModel::setSecondaryFilterRole(int role)
 {
     m_secondaryFilterRole = role;
-    Q_EMIT secondaryFilterRoleChanged();
 }
 
 QString CompletionProxyModel::filterText() const
@@ -55,7 +53,6 @@ QString CompletionProxyModel::filterText() const
 void CompletionProxyModel::setFilterText(const QString &filterText)
 {
     m_filterText = filterText;
-    Q_EMIT filterTextChanged();
 }
 
 void CompletionProxyModel::setFullText(const QString &fullText)

src/models/completionproxymodel.h

@@ -5,28 +5,71 @@
 
 #include <QSortFilterProxyModel>
 
+/**
+ * @class CompletionProxyModel
+ *
+ * A filter model to sort and filter completion results.
+ *
+ * This model is designed to work with multiple source models depending upon the
+ * completion type.
+ *
+ * A model value will be shown if its primary or secondary role values start with
+ * the filter text. The exception is if the full text perfectly matches
+ * the primary filter role value in which case the completion ends (i.e. the filter
+ * will return no results).
+ *
+ * @note The filter is primarily design to work with strings, therefore make sure
+ *       that the source model roles that are to be filtered are strings.
+ */
 class CompletionProxyModel : public QSortFilterProxyModel
 {
     Q_OBJECT
-    Q_PROPERTY(int secondaryFilterRole READ secondaryFilterRole WRITE setSecondaryFilterRole NOTIFY secondaryFilterRoleChanged)
-    Q_PROPERTY(QString filterText READ filterText WRITE setFilterText NOTIFY filterTextChanged)
 
 public:
+    /**
+     * @brief Wether a row should be shown or not.
+     *
+     * @sa QSortFilterProxyModel::filterAcceptsRow
+     */
     bool filterAcceptsRow(int sourceRow, const QModelIndex &sourceParent) const override;
+
+    /**
+     * @brief Returns true if the value of source_left is less than source_right.
+     *
+     * @sa QSortFilterProxyModel::lessThan
+     */
     bool lessThan(const QModelIndex &source_left, const QModelIndex &source_right) const override;
 
+    /**
+     * @brief Get the current secondary filter role.
+     */
     int secondaryFilterRole() const;
+
+    /**
+     * @brief Set the secondary filter role.
+     *
+     * Refer to the source model for what value corresponds to what role.
+     */
     void setSecondaryFilterRole(int role);
 
+    /**
+     * @brief Get the current text being used to filter the source model.
+     */
     QString filterText() const;
+
+    /**
+     * @brief Set the text to be used to filter the source model.
+     */
     void setFilterText(const QString &filterText);
 
+    /**
+     * @brief Set the full text in the chatbar after the completion start.
+     *
+     * This is used to automatically end the completion if the user replicated the
+     * primary filter role value perfectly.
+     */
     void setFullText(const QString &fullText);
 
-Q_SIGNALS:
-    void secondaryFilterRoleChanged();
-    void filterTextChanged();
-
 private:
     int m_secondaryFilterRole = -1;
     QString m_filterText;