From e2a842a0d0914ad56bb08471cfb3ee3ab7082ace Mon Sep 17 00:00:00 2001
From: ivan tkachenko <me@ratijas.tk>
Date: Wed, 18 May 2022 01:57:07 +0300
Subject: [PATCH] [lookandfeel] Document types of a user list model

---
 components/sessionsprivate/sessionsmodel.h    |  1 +
 .../components/SessionManagementScreen.qml    | 24 ++++++++++++-------
 lookandfeel/contents/components/UserList.qml  | 18 ++++++++++++++
 3 files changed, 34 insertions(+), 9 deletions(-)

diff --git a/components/sessionsprivate/sessionsmodel.h b/components/sessionsprivate/sessionsmodel.h
index a3049d80e..a929cf057 100644
--- a/components/sessionsprivate/sessionsmodel.h
+++ b/components/sessionsprivate/sessionsmodel.h
@@ -33,6 +33,7 @@ struct SessionEntry {
 
 class KDisplayManager;
 
+// This model should be compatible with SDDM::SessionModel
 class SessionsModel : public QAbstractListModel
 {
     Q_OBJECT
diff --git a/lookandfeel/contents/components/SessionManagementScreen.qml b/lookandfeel/contents/components/SessionManagementScreen.qml
index 0e2667385..ef9ab5fc1 100644
--- a/lookandfeel/contents/components/SessionManagementScreen.qml
+++ b/lookandfeel/contents/components/SessionManagementScreen.qml
@@ -30,16 +30,22 @@ FocusScope {
     property alias actionItemsVisible: actionItemsLayout.visible
 
     /*
-     * A model with a list of users to show in the view
-     * The following roles should exist:
-     *  - name
-     *  - iconSource
+     * A model with a list of users to show in the view.
+     * There are different implementations in sddm greeter (UserModel) and
+     * KScreenLocker (SessionsModel), so some roles will be missing.
      *
-     * The following are also handled:
-     *  - vtNumber
-     *  - displayNumber
-     *  - session
-     *  - isTty
+     * type: {
+     *  name: string,
+     *  realName: string,
+     *  homeDir: string,
+     *  icon: string,
+     *  iconName?: string,
+     *  needsPassword?: bool,
+     *  displayNumber?: string,
+     *  vtNumber?: int,
+     *  session?: string
+     *  isTty?: bool,
+     * }
      */
     property alias userListModel: userListView.model
 
diff --git a/lookandfeel/contents/components/UserList.qml b/lookandfeel/contents/components/UserList.qml
index becc65101..e3d272856 100644
--- a/lookandfeel/contents/components/UserList.qml
+++ b/lookandfeel/contents/components/UserList.qml
@@ -8,6 +8,24 @@ import QtQuick 2.15
 
 import org.kde.plasma.core 2.0 as PlasmaCore
 
+/*
+ * A model with a list of users to show in the view.
+ * There are different implementations in sddm greeter (UserModel) and
+ * KScreenLocker (SessionsModel), so some roles will be missing.
+ *
+ * type: {
+ *  name: string,
+ *  realName: string,
+ *  homeDir: string,
+ *  icon: string,
+ *  iconName?: string,
+ *  needsPassword?: bool,
+ *  displayNumber?: string,
+ *  vtNumber?: int,
+ *  session?: string
+ *  isTty?: bool,
+ * }
+ */
 ListView {
     id: view
     readonly property string selectedUser: currentItem ? currentItem.userName : ""