Improvements to Unified Friends List Guide

docs/discord-social-sdk/development-guides/creating-a-unified-friends-list.mdx

@@ -61,7 +61,7 @@ First, let's create a function to see what kind of relationships and information
 ```cpp
 void DisplayFriendsList(discordpp::Client& client) {
     std::vector<std::string> relationships{};
-    for (auto& relationship: client.GetRelationships()) {
+    for (auto& relationship: client->GetRelationships()) {
         auto user = relationship.User();
         if (!user) {
             continue;
@@ -91,6 +91,13 @@ void DisplayFriendsList(discordpp::Client& client) {
 }
 ```
 
+:::info
+The `relationship.User()` function returns a [`UserHandle`] object that represents a user that the Discord Social SDK
+knows about.
+Handle objects maintain references to both the underlying data and the SDK instance, which means that when their
+data changes, existing handle objects automatically reflect these changes without needing to be recreated.
+:::
+
 We will want to call this function when the client is ready, so let's add it to our ready callback:
 
 ```cpp
@@ -141,7 +148,7 @@ void DisplayFriendsList(discordpp::Client& client) {
     std::vector<std::string> online;
     std::vector<std::string> offline;
 
-    for (auto& relationship : client.GetRelationships()) {
+    for (auto& relationship : client->GetRelationships()) {
         auto user = relationship.User();
         if (!user) {
             continue;
@@ -209,21 +216,51 @@ void DisplayFriendsList(discordpp::Client& client) {
 
 If we build and run our application, we should now see a list of friends separated into three categories: `Online - GameTitle`, `Online - Elsewhere`, and `Offline`.
 
+## Step 3: Monitor Changes to Users
+
+To monitor for user changes, we're going using the [`Client::SetUserUpdatedCallback`] function.
+
+This callback will be triggered whenever a user's info is updated, such as name or presence changes (when they go online, offline, or start playing your game).
+
+```cpp
+client->SetUserUpdatedCallback([&client](uint64_t userId) {
+    std::cout << "👤 User updated: " << userId << std::endl;
+    DisplayFriendsList(*client);
+});
+```
+
+Now your friends list will automatically update when the presence of a friend changes, such as when they go online, offline or start playing your game.
+
+:::info
+The automatic updates of the [`UserHandle`] object to the latest the user information should be sufficient for
+retrieving the most up-to-date user information.
+[`Client::SetUserUpdatedCallback`] may be more useful to identify times when you wish to re-sort your
+user list, or similar operations.
+:::
 ---
 
-## Step 3: Monitor Changes in Relationships
+## Step 4: Monitor Changes in Relationships
 
-Let's setup two callbacks to handle relationship updates.
+Let us setup two callbacks to handle relationship updates.
+
+:::warn
+These examples rebuild the friends list from scratch every time a relationship changes. For performance reasons, we
+recommend maintaining a collection of [`UserHandle`] objects and adding and removing them appropriately.
+:::
 
 ### Relationship Created Callback
 
 This can happen when a user sends or accepts a friend invite, or blocks a user.
 
 ```cpp
 client->SetRelationshipCreatedCallback([&client](uint64_t userId, bool isDiscordRelationshipUpdate) {
-    std::cout << "🤝 Relationship created: " << userId << std::endl;
-    DisplayFriendsList(*client);
-}); 
+    std::optional<discordpp::UserHandle> user = client->GetUser(userId);
+    // if the userid is valid (which it should be), we can display the user's display name
+    if(user) {
+        std::cout << "🤝 Relationship created: " << user->DisplayName() << std::endl;
+        DisplayFriendsList(*client);
+    }
+});
 ```
 
 ### Relationship Deleted Callback
@@ -239,29 +276,6 @@ client->SetRelationshipDeletedCallback([&client](uint64_t userId, bool isDiscord
 
 Now your friends list will automatically update when relationships change, such as when you add a new friend, accept a friend request, or block a user.
 
-:::warn
-Note: Our example will rebuild the friends list from scratch every time a relationship changes. For performance reasons, you will want to update only the changed relationships.
-:::
-
-## Step 4: Monitor Changes to Users 
-
-To monitor for user changes, we're going using the [`Client::SetUserUpdatedCallback`] function. 
-
-This callback will be triggered whenever a user's info is updated, such as name or presence changes (when they go online, offline, or start playing your game).
-
-```cpp
-client->SetUserUpdatedCallback([&client](uint64_t userId) {
-    std::cout << "👤 User updated: " << userId << std::endl;
-    DisplayFriendsList(*client);
-});
-```
-
-Now your friends list will automatically update when the presence of a friend changes, such as when they go online, offline or start playing your game.
-
-:::warn
-Note: Our example will rebuild the friends list from scratch every time a relationship changes. For performance reasons, you will want to update only the user or relationship that changed.
-:::
-
 ---
 
 ## Next Steps
@@ -292,4 +306,5 @@ Now that you have a unified friends list, you can build on your social features
 
 {/* Autogenerated Reference Links */}
 [`Client::GetRelationships`]: https://discord.com/developers/docs/social-sdk/classdiscordpp_1_1Client.html#ad481849835cd570f0e03adafcf90125d
-[`Client::SetUserUpdatedCallback`]: https://discord.com/developers/docs/social-sdk/classdiscordpp_1_1Client.html#a3559f375165acedc6d6677ef599b3a4a
+[`Client::SetUserUpdatedCallback`]: https://discord.com/developers/docs/social-sdk/classdiscordpp_1_1Client.html#a3559f375165acedc6d6677ef599b3a4a
+[`UserHandle`]: https://discord.com/developers/docs/social-sdk/classdiscordpp_1_1UserHandle.html#a3c4e8166cb923dbb7b778ef87b73fd34