From d6110fa064cddc8fd27ffaadf959f0c5bb5882e6 Mon Sep 17 00:00:00 2001
From: Erik Johnston <erikj@element.io>
Date: Thu, 18 Jun 2026 13:52:40 +0000
Subject: [PATCH] Add field-level doc comments to SerializeEventConfig

---
 rust/src/events/serialize.rs    | 18 ++++++++++++++++
 synapse/synapse_rust/events.pyi | 38 +++++++++++++++++++++++++++------
 2 files changed, 49 insertions(+), 7 deletions(-)

diff --git a/rust/src/events/serialize.rs b/rust/src/events/serialize.rs
index 465fde3d9e..76ac613685 100644
--- a/rust/src/events/serialize.rs
+++ b/rust/src/events/serialize.rs
@@ -99,12 +99,30 @@ pub enum EventFormat {
 #[pyclass(frozen, skip_from_py_object)]
 #[derive(Clone)]
 pub struct SerializeEventConfig {
+    /// Whether to apply the client event format transform (v1/v2/raw). When
+    /// `false`, the federation-format event is returned as-is.
     as_client_event: bool,
+    /// Which client event format variant to apply (only used when
+    /// `as_client_event` is `true`).
     event_format: EventFormat,
+    /// The entity requesting the event. Used to gate sender-only fields such as
+    /// `transaction_id` and `delay_id`.
     requester: Option<Requester>,
+    /// If set, only include these field paths in the output. An empty list
+    /// returns an empty event; `None` returns all fields.
+    ///
+    /// The fields can be "dotted" fields, e.g. `content.body`.
     event_field_allowlist: Option<Vec<String>>,
+    /// Whether to include `invite_room_state` / `knock_room_state` in
+    /// `unsigned`. These are stripped by default and only included for specific
+    /// endpoints (e.g. `/sync` invite/knock handling).
     include_stripped_room_state: bool,
+    /// When `true`, add server-admin-only metadata to `unsigned`
+    /// (`io.element.synapse.soft_failed`,
+    /// `io.element.synapse.policy_server_spammy`).
     include_admin_metadata: bool,
+    /// Whether MSC4354 (sticky events) is enabled. When `true`, the remaining
+    /// stickiness TTL is computed and added to `unsigned`.
     msc4354_enabled: bool,
 }
 
diff --git a/synapse/synapse_rust/events.pyi b/synapse/synapse_rust/events.pyi
index a741cb3944..2b87953088 100644
--- a/synapse/synapse_rust/events.pyi
+++ b/synapse/synapse_rust/events.pyi
@@ -373,19 +373,43 @@ class SerializeEventConfig:
         msc4354_enabled: bool = False,
     ) -> None: ...
     @property
-    def as_client_event(self) -> bool: ...
+    def as_client_event(self) -> bool:
+        """Whether to apply the client event format transform (v1/v2/raw). When
+        ``False``, the federation-format event is returned as-is."""
+
     @property
-    def event_format(self) -> EventFormat: ...
+    def event_format(self) -> EventFormat:
+        """Which client event format variant to apply (only used when
+        ``as_client_event`` is ``True``)."""
+
     @property
-    def requester(self) -> Requester | None: ...
+    def requester(self) -> Requester | None:
+        """The entity requesting the event. Used to gate sender-only fields such
+        as ``transaction_id`` and ``delay_id``."""
+
     @property
-    def event_field_allowlist(self) -> list[str] | None: ...
+    def event_field_allowlist(self) -> list[str] | None:
+        """If set, only include these field paths in the output. An empty list
+        returns an empty event; ``None`` returns all fields.
+
+        The fields can be "dotted" fields, e.g. ``content.body``."""
+
     @property
-    def include_stripped_room_state(self) -> bool: ...
+    def include_stripped_room_state(self) -> bool:
+        """Whether to include ``invite_room_state`` / ``knock_room_state`` in
+        ``unsigned``. These are stripped by default and only included for
+        specific endpoints (e.g. ``/sync`` invite/knock handling)."""
+
     @property
-    def include_admin_metadata(self) -> bool: ...
+    def include_admin_metadata(self) -> bool:
+        """When ``True``, add server-admin-only metadata to ``unsigned``
+        (``io.element.synapse.soft_failed``,
+        ``io.element.synapse.policy_server_spammy``)."""
+
     @property
-    def msc4354_enabled(self) -> bool: ...
+    def msc4354_enabled(self) -> bool:
+        """Whether MSC4354 (sticky events) is enabled. When ``True``, the
+        remaining stickiness TTL is computed and added to ``unsigned``."""
     def for_admin(self) -> SerializeEventConfig:
         """Return a copy of this config with ``include_admin_metadata`` enabled."""