From 2cd6f9626d31cc81775cf5266900b6510e090129 Mon Sep 17 00:00:00 2001
From: Timo <toger5@hotmail.de>
Date: Tue, 17 Dec 2024 11:10:46 +0100
Subject: [PATCH] add docs to `SessionMembershipData`

---
 src/matrixrtc/CallMembership.ts | 36 +++++++++++++++++++++++++++++++--
 1 file changed, 34 insertions(+), 2 deletions(-)

diff --git a/src/matrixrtc/CallMembership.ts b/src/matrixrtc/CallMembership.ts
index ef72480654..5f01f6fc86 100644
--- a/src/matrixrtc/CallMembership.ts
+++ b/src/matrixrtc/CallMembership.ts
@@ -28,20 +28,52 @@ type CallScope = "m.room" | "m.user";
  * Represents an entry in the memberships section of an m.call.member event as it is on the wire.
  **/
 export type SessionMembershipData = {
+    /**
+     * The RTC application defines the type of the RTC session.
+     */
     application: string;
+
+    /**
+     * The id of this session.
+     * A session can never span over multiple rooms so this id is to distinguish between
+     * multiple session in one room. A room wide session that is not associated with a user,
+     * and therefore immune to creation race conflicts, uses the `call_id: ""`.
+     */
     call_id: string;
     device_id: string;
 
+    /**
+     * The focus selection system this user/membership is using.
+     */
     focus_active: Focus;
+
+    /**
+     * A list of possible foci this uses knows about. One of them might be used based on the focus_active
+     * selection system.
+     */
     foci_preferred: Focus[];
+
+    /**
+     * Optional field that contains the creation of the session. If it is undefined the creation
+     * is the `origin_server_ts` of the event itself. For updates to the event this property tracks
+     * the `origin_server_ts` of the initial join event.
+     *  - If it is undefined it can be interpreted as a "Join".
+     *  - If it is defined it can be interpreted as an "Update"
+     */
     created_ts?: number;
 
     // Application specific data
+
+    /**
+     * If the `application` = `"m.call"` this defines if it is a room or user owned call.
+     * There can always be one room scroped call but multiple user owned calls (breakout sessions)
+     */
     scope?: CallScope;
 
     /**
-     * Optionally we allow to define a delta to the created_ts when it expires. This should be set to multiple hours.
-     * The only reason it exist is if delayed events fail. (for example because if a homeserver crashes)
+     * Optionally we allow to define a delta to the `created_ts` that defines when the event is expired/invalid.
+     * This should be set to multiple hours. The only reason it exist is to deal with failed delayed events.
+     * (for example caused by a homeserver crashes)
      **/
     expires?: number;
 };