From c253f93290f6b00d337c0f6865952db65847594b Mon Sep 17 00:00:00 2001 From: Greg Price Date: Tue, 4 Feb 2025 20:35:22 -0800 Subject: [PATCH] user [nfc]: Document users map, especially its incompleteness --- lib/model/user.dart | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/lib/model/user.dart b/lib/model/user.dart index 2e829132b0..04a46e071f 100644 --- a/lib/model/user.dart +++ b/lib/model/user.dart @@ -4,6 +4,24 @@ import '../api/model/model.dart'; /// The portion of [PerAccountStore] describing the users in the realm. mixin UserStore { + /// All known users in the realm, by [User.userId]. + /// + /// There may be other users not found in this map, for multiple reasons: + /// + /// * The self-user may not have permission to see all the users in the + /// realm, for example because the self-user is a guest. + /// + /// * Because of the fetch/event race, any data that the client fetched + /// outside of the event system may reflect an earlier or later time + /// than this data, which is maintained by the event system. + /// This includes messages fetched for a message list, and notifications. + /// Those may therefore refer to users for which we have yet to see the + /// [RealmUserAddEvent], or have already handled a [RealmUserRemoveEvent]. + /// + /// Code that looks up a user in this map should therefore always handle + /// the possibility that the user is not found (except + /// where there is a specific reason to know the user should be found). + /// Consider using [ZulipLocalizations.unknownUserName]. Map get users; }