From 5c2c6abc3da95dc1bcf03314eb08d63250ea2062 Mon Sep 17 00:00:00 2001
From: Patrick Cloke <clokep@patrick.cloke.us>
Date: Mon, 12 Aug 2024 16:42:12 -0400
Subject: [PATCH 1/2] Add missing docstrings related to profile methods.

---
 synapse/handlers/profile.py               | 35 +++++++++++++++++++++++
 synapse/storage/databases/main/profile.py | 34 ++++++++++++++++++++++
 2 files changed, 69 insertions(+)

diff --git a/synapse/handlers/profile.py b/synapse/handlers/profile.py
index 6663d4b271..af8cd838ee 100644
--- a/synapse/handlers/profile.py
+++ b/synapse/handlers/profile.py
@@ -74,6 +74,17 @@ def __init__(self, hs: "HomeServer"):
         self._third_party_rules = hs.get_module_api_callbacks().third_party_event_rules
 
     async def get_profile(self, user_id: str, ignore_backoff: bool = True) -> JsonDict:
+        """
+        Get a user's profile as a JSON dictionary.
+
+        Args:
+            user_id: The user to fetch the profile of.
+            ignore_backoff: True to ignore backoff when fetching over federation.
+
+        Returns:
+            A JSON dictionary. For local queries this will include the displayname and avatar_url
+            fields. For remote queries it may contain arbitrary information.
+        """
         target_user = UserID.from_string(user_id)
 
         if self.hs.is_mine(target_user):
@@ -107,6 +118,15 @@ async def get_profile(self, user_id: str, ignore_backoff: bool = True) -> JsonDi
                 raise e.to_synapse_error()
 
     async def get_displayname(self, target_user: UserID) -> Optional[str]:
+        """
+        Fetch a user's display name from their profile.
+
+        Args:
+            target_user: The user to fetch the display name of.
+
+        Returns:
+            The user's display name or None if unset.
+        """
         if self.hs.is_mine(target_user):
             try:
                 displayname = await self.store.get_profile_displayname(target_user)
@@ -203,6 +223,15 @@ async def set_displayname(
             await self._update_join_states(requester, target_user)
 
     async def get_avatar_url(self, target_user: UserID) -> Optional[str]:
+        """
+        Fetch a user's avatar URL from their profile.
+
+        Args:
+            target_user: The user to fetch the avatar URL of.
+
+        Returns:
+            The user's avatar URL or None if unset.
+        """
         if self.hs.is_mine(target_user):
             try:
                 avatar_url = await self.store.get_profile_avatar_url(target_user)
@@ -403,6 +432,12 @@ async def on_profile_query(self, args: JsonDict) -> JsonDict:
     async def _update_join_states(
         self, requester: Requester, target_user: UserID
     ) -> None:
+        """
+        Update the membership events of each room the user is joined to with the
+        new profile information.
+
+        Note that this stomps over any custom display name or avatar URL in member events.
+        """
         if not self.hs.is_mine(target_user):
             return
 
diff --git a/synapse/storage/databases/main/profile.py b/synapse/storage/databases/main/profile.py
index 996aea808d..41cf08211f 100644
--- a/synapse/storage/databases/main/profile.py
+++ b/synapse/storage/databases/main/profile.py
@@ -144,6 +144,16 @@ def _final_batch(txn: LoggingTransaction, lower_bound_id: str) -> None:
         return 50
 
     async def get_profileinfo(self, user_id: UserID) -> ProfileInfo:
+        """
+        Fetch the display name and avatar URL of a user.
+
+        Args:
+            user_id: The user ID to fetch the profile for.
+
+        Returns:
+            The user's display name and avatar URL. Values may be null if unset
+             or if the user doesn't exist.
+        """
         profile = await self.db_pool.simple_select_one(
             table="profiles",
             keyvalues={"full_user_id": user_id.to_string()},
@@ -158,6 +168,15 @@ async def get_profileinfo(self, user_id: UserID) -> ProfileInfo:
         return ProfileInfo(avatar_url=profile[1], display_name=profile[0])
 
     async def get_profile_displayname(self, user_id: UserID) -> Optional[str]:
+        """
+        Fetch the display name of a user.
+
+        Args:
+            user_id: The user to get the display name for.
+
+        Raises:
+            404 if the user does not exist.
+        """
         return await self.db_pool.simple_select_one_onecol(
             table="profiles",
             keyvalues={"full_user_id": user_id.to_string()},
@@ -166,6 +185,15 @@ async def get_profile_displayname(self, user_id: UserID) -> Optional[str]:
         )
 
     async def get_profile_avatar_url(self, user_id: UserID) -> Optional[str]:
+        """
+        Fetch the avatar URL of a user.
+
+        Args:
+            user_id: The user to get the avatar URL for.
+
+        Raises:
+            404 if the user does not exist.
+        """
         return await self.db_pool.simple_select_one_onecol(
             table="profiles",
             keyvalues={"full_user_id": user_id.to_string()},
@@ -174,6 +202,12 @@ async def get_profile_avatar_url(self, user_id: UserID) -> Optional[str]:
         )
 
     async def create_profile(self, user_id: UserID) -> None:
+        """
+        Create a blank profile for a user.
+
+        Args:
+            user_id: The user to create the profile for.
+        """
         user_localpart = user_id.localpart
         await self.db_pool.simple_insert(
             table="profiles",

From 6384a6adaf4e439c62f92c1eb23bd35039a55962 Mon Sep 17 00:00:00 2001
From: Patrick Cloke <clokep@patrick.cloke.us>
Date: Tue, 13 Aug 2024 06:37:43 -0400
Subject: [PATCH 2/2] Newsfragment

---
 changelog.d/17559.doc | 1 +
 1 file changed, 1 insertion(+)
 create mode 100644 changelog.d/17559.doc

diff --git a/changelog.d/17559.doc b/changelog.d/17559.doc
new file mode 100644
index 0000000000..e54a122b74
--- /dev/null
+++ b/changelog.d/17559.doc
@@ -0,0 +1 @@
+Improve docstrings for profile methods.