From 77a2348615a2b2e857e186f7b8592d17b2ada0d0 Mon Sep 17 00:00:00 2001
From: Erik Johnston <erik@matrix.org>
Date: Wed, 27 May 2026 16:39:34 +0100
Subject: [PATCH] Transfer existing and previous docstrings to events.pyi

---
 rust/src/events/mod.rs          |  6 +++++
 synapse/synapse_rust/events.pyi | 45 +++++++++++++++++++++++++--------
 2 files changed, 41 insertions(+), 10 deletions(-)

diff --git a/rust/src/events/mod.rs b/rust/src/events/mod.rs
index 0a1cc8314b..3703e3d9f2 100644
--- a/rust/src/events/mod.rs
+++ b/rust/src/events/mod.rs
@@ -278,6 +278,8 @@ impl Event {
         self.rejected_reason.as_deref()
     }
 
+    /// Returns the list of prev event IDs. The order matches the order
+    /// specified in the event, though there is no meaning to it.
     fn prev_event_ids(&self) -> Vec<String> {
         match &*self.parsed_event.specific_fields {
             EventFormatEnum::V1(format) => format.prev_event_ids(),
@@ -287,6 +289,8 @@ impl Event {
         }
     }
 
+    /// Returns the list of auth event IDs. The order matches the order
+    /// specified in the event, though there is no meaning to it.
     fn auth_event_ids(&self) -> PyResult<Vec<String>> {
         match &*self.parsed_event.specific_fields {
             EventFormatEnum::V1(format) => Ok(format.auth_event_ids()),
@@ -312,10 +316,12 @@ impl Event {
         self.parsed_event.common_fields.state_key.is_some()
     }
 
+    /// Get the state key of this event, or None if it's not a state event.
     fn get_state_key(&self) -> Option<&str> {
         self.parsed_event.common_fields.state_key.as_deref_opt()
     }
 
+    /// The EventFormatVersion implemented by this event.
     #[getter]
     fn format_version(&self) -> i32 {
         self.room_version.event_format
diff --git a/synapse/synapse_rust/events.pyi b/synapse/synapse_rust/events.pyi
index b6a68c48b9..28404314ca 100644
--- a/synapse/synapse_rust/events.pyi
+++ b/synapse/synapse_rust/events.pyi
@@ -235,10 +235,22 @@ class Event:
         internal_metadata_dict: JsonDict,
         rejected_reason: str | None,
     ) -> None: ...
-    def get_dict(self) -> JsonDict: ...
-    def get_dict_for_persistence(self) -> JsonDict: ...
-    def get_pdu_json(self, time_now: int | None = None) -> JsonDict: ...
-    def get_templated_pdu_json(self) -> JsonDict: ...
+    def get_dict(self) -> JsonDict:
+        """Convert the event to a dictionary suitable for serialisation."""
+
+    def get_dict_for_persistence(self) -> JsonDict:
+        """Like ``get_dict``, but serializes ``unsigned`` in a form suitable for
+        persistence."""
+
+    def get_pdu_json(self, time_now: int | None = None) -> JsonDict:
+        """Like ``get_dict``, but serializes ``unsigned`` in a form suitable
+        for sending over federation."""
+
+    def get_templated_pdu_json(self) -> JsonDict:
+        """Like ``get_dict``, except strips fields like ``signatures``,
+        ``hashes`` and ``unsigned`` so that the result is suitable as a template for
+        creating new events. Used in make_{join,leave,knock} flows."""
+
     @property
     def event_id(self) -> str: ...
     @property
@@ -268,18 +280,31 @@ class Event:
     @property
     def room_version(self) -> RoomVersion: ...
     @property
-    def format_version(self) -> int: ...
+    def format_version(self) -> int:
+        """The EventFormatVersion implemented by this event."""
+
     @property
     def membership(self) -> Any: ...
     @property
     def redacts(self) -> Any | None: ...
-    def prev_event_ids(self) -> StrSequence: ...
-    def auth_event_ids(self) -> StrSequence: ...
+    def prev_event_ids(self) -> StrSequence:
+        """Returns the list of prev event IDs."""
+
+    def auth_event_ids(self) -> StrSequence:
+        """Returns the list of auth event IDs"""
+
     def is_state(self) -> bool: ...
-    def get_state_key(self) -> str | None: ...
+    def get_state_key(self) -> str | None:
+        """Get the state key of this event, or None if it's not a state event."""
     def __contains__(self, key: str) -> bool: ...
     def get(self, key: str, default: Any = None) -> Any: ...
     def items(self) -> list[tuple[str, Any]]: ...
     def keys(self) -> list[str]: ...
-    def deep_copy(self) -> "Event": ...
-    def sticky_duration(self) -> Duration | None: ...
+    def deep_copy(self) -> "Event":
+        """Returns a deep copy of this object, such that modifying the copy will
+        not affect the original."""
+
+    def sticky_duration(self) -> Duration | None:
+        """If this event has the ``msc4354_sticky`` top-level field, returns a
+        ``SynapseDuration`` representing the sticky duration. Otherwise returns
+        ``None``."""