From 31ba7b82d8bce3fef9b5e331c2bec6fa4d03ec2a Mon Sep 17 00:00:00 2001
From: Ivan Enderlin <ivan@mnt.io>
Date: Thu, 8 Feb 2024 15:25:41 +0100
Subject: [PATCH] doc(sdk,base,ffi): Improve documentation and rename
 `favorite` to `favourite`.

The Matrix specification uses the `m.favourite` orthography. Let's use
the same in our code. So `set_is_favorite` becomes `set_is_favourite`.
This patch updates this in various places for the sake of consistency.
---
 bindings/matrix-sdk-ffi/src/room.rs     |  4 ++--
 crates/matrix-sdk-base/src/rooms/mod.rs |  4 ++--
 crates/matrix-sdk/src/room/mod.rs       | 22 ++++++++++++----------
 3 files changed, 16 insertions(+), 14 deletions(-)

diff --git a/bindings/matrix-sdk-ffi/src/room.rs b/bindings/matrix-sdk-ffi/src/room.rs
index e2c3b2363..8b76f5419 100644
--- a/bindings/matrix-sdk-ffi/src/room.rs
+++ b/bindings/matrix-sdk-ffi/src/room.rs
@@ -256,12 +256,12 @@ impl Room {
         })))
     }
 
-    pub async fn set_is_favorite(
+    pub async fn set_is_favourite(
         &self,
         is_favorite: bool,
         tag_order: Option<f64>,
     ) -> Result<(), ClientError> {
-        self.inner.set_is_favorite(is_favorite, tag_order).await?;
+        self.inner.set_is_favourite(is_favorite, tag_order).await?;
         Ok(())
     }
 
diff --git a/crates/matrix-sdk-base/src/rooms/mod.rs b/crates/matrix-sdk-base/src/rooms/mod.rs
index 71b05e73c..9ee1ed230 100644
--- a/crates/matrix-sdk-base/src/rooms/mod.rs
+++ b/crates/matrix-sdk-base/src/rooms/mod.rs
@@ -105,7 +105,7 @@ pub struct BaseRoomInfo {
     /// memberships.
     #[serde(skip_serializing_if = "BTreeMap::is_empty", default)]
     pub(crate) rtc_member: BTreeMap<OwnedUserId, MinimalStateEvent<CallMemberEventContent>>,
-    // Whether this room has been manually marked as unread
+    /// Whether this room has been manually marked as unread.
     #[serde(default)]
     pub(crate) is_marked_unread: bool,
     /// Some notable tags.
@@ -318,7 +318,7 @@ bitflags! {
     /// others, and this struct describe them.
     #[repr(transparent)]
     #[derive(Debug, Default, Clone, Copy, Deserialize, Serialize)]
-    pub struct NotableTags: u8 {
+    pub(crate) struct NotableTags: u8 {
         /// The `m.favourite` tag.
         const FAVOURITE = 0b0000_0001;
 
diff --git a/crates/matrix-sdk/src/room/mod.rs b/crates/matrix-sdk/src/room/mod.rs
index d1972b912..0548184e4 100644
--- a/crates/matrix-sdk/src/room/mod.rs
+++ b/crates/matrix-sdk/src/room/mod.rs
@@ -968,16 +968,17 @@ impl Room {
         self.client.send(request, None).await
     }
 
-    /// Update the is_favorite flag from the room by calling set_tag or
-    /// remove_tag method on `m.favourite` tag.
-    /// If `is_favorite` is `true`, and `m.low_priority` tag is set on the room,
-    /// the tag will be removed too.
+    /// Add or remove the `m.favourite` flag for this room.
+    ///
+    /// If `is_favourite` is `true`, and the `m.low_priority` tag is set on the
+    /// room, the tag will be removed too.
+    ///
     /// # Arguments
     ///
-    /// * `is_favorite` - Whether to mark this room as favorite or not.
+    /// * `is_favourite` - Whether to mark this room as favourite.
     /// * `tag_order` - The order of the tag if any.
-    pub async fn set_is_favorite(&self, is_favorite: bool, tag_order: Option<f64>) -> Result<()> {
-        if is_favorite {
+    pub async fn set_is_favourite(&self, is_favourite: bool, tag_order: Option<f64>) -> Result<()> {
+        if is_favourite {
             let tag_info = assign!(TagInfo::new(), { order: tag_order });
 
             self.set_tag(TagName::Favorite, tag_info).await?;
@@ -991,10 +992,11 @@ impl Room {
         Ok(())
     }
 
-    /// Update the is_low_priority flag from the room by calling set_tag or
-    /// remove_tag method on `m.low_priority` tag.
-    /// If `is_low_priority` is `true`, and `m.favourite` tag is set on the
+    /// Add or remove the `m.lowpriority` flag for this room.
+    ///
+    /// If `is_low_priority` is `true`, and the `m.favourite` tag is set on the
     /// room, the tag will be removed too.
+    ///
     /// # Arguments
     ///
     /// * `is_low_priority` - Whether to mark this room as low_priority or not.