Add script to check that the tsdoc is correct and up-to-date

src/e2ee/sharedKeyManagement.ts

@@ -34,8 +34,8 @@ const getRoomSharedKeyLocalStorageKey = (roomId: string): string =>
   `room-shared-key-${roomId}`;
 
 /**
- * An upto-date shared key for the room. Either from local storage or the value from `setInitialValue`.
- * @param roomId
+ * An up-to-date shared key for the room. Either from local storage or the value from `setInitialValue`.
+ * @param roomId The room ID we want the shared key for.
  * @param setInitialValue The value we get from the URL. The hook will overwrite the local storage value with this.
  * @returns [roomSharedKey, setRoomSharedKey] like a react useState hook.
  */

src/livekit/MatrixAudioRenderer.tsx

@@ -166,7 +166,11 @@ interface StereoPanAudioTrackProps {
  * It main purpose is to remount the AudioTrack component when switching from
  * audioContext to normal audio playback.
  * As of now the AudioTrack component does not support adding audio nodes while being mounted.
- * @param param0
+ * @param props The component props
+ * @param props.trackRef The track reference
+ * @param props.muted If the track should be muted
+ * @param props.audioContext The audio context to use
+ * @param props.audioNodes The audio nodes to use
  * @returns
  */
 function AudioTrackWithAudioNodes({

src/livekit/openIDSFU.ts

@@ -63,9 +63,9 @@ export type OpenIDClientParts = Pick<
  * Gets a bearer token from the homeserver and then use it to authenticate
  * to the matrix RTC backend in order to get acces to the SFU.
  * It has built-in retry for calls to the homeserver with a backoff policy.
- * @param client
- * @param serviceUrl
- * @param matrixRoomId
+ * @param client The Matrix client
+ * @param serviceUrl The URL of the livekit SFU service
+ * @param matrixRoomId The Matrix room ID for which to get the SFU config
  * @returns Object containing the token information
  * @throws FailToGetOpenIdToken
  */

src/reactions/ReactionsReader.ts

@@ -135,10 +135,10 @@ export class ReactionsReader {
   }
 
   /**
-   * Fetchest any hand wave reactions by the given sender on the given
+   * Fetches any hand wave reactions by the given sender on the given
    * membership event.
-   * @param membershipEventId
-   * @param expectedSender
+   * @param membershipEventId - The user membership event id.
+   * @param expectedSender - The expected sender of the reaction.
    * @returns A MatrixEvent if one was found.
    */
   private getLastReactionEvent(

src/room/useLoadGroupCall.ts

@@ -106,22 +106,18 @@ async function joinRoomAfterInvite(
 
 export class CallTerminatedMessage extends Error {
   /**
+   * Creates a new CallTerminatedMessage.
+   *
+   * @param icon The icon to display with the message
    * @param messageTitle The title of the call ended screen message (translated)
+   * @param messageBody The message explaining the kind of termination
+   * (kick, ban, knock reject, etc.) (translated)
+   * @param reason  The user-provided reason for the termination (kick/ban)
    */
   public constructor(
-    /**
-     * The icon to display with the message.
-     */
     public readonly icon: ComponentType<SVGAttributes<SVGElement>>,
     messageTitle: string,
-    /**
-     * The message explaining the kind of termination (kick, ban, knock reject,
-     * etc.) (translated)
-     */
     public readonly messageBody: string,
-    /**
-     * The user-provided reason for the termination (kick/ban)
-     */
     public readonly reason?: string,
   ) {
     super(messageTitle);

src/settings/rageshake.ts

@@ -99,7 +99,7 @@ class ConsoleLogger extends EventEmitter {
 
   /**
    * Returns the log lines to flush to disk and empties the internal log buffer
-   * @return {string} \n delimited log lines
+   * @return \n delimited log lines
    */
   public popLogs(): string {
     const logsToFlush = this.logs;
@@ -109,7 +109,7 @@ class ConsoleLogger extends EventEmitter {
 
   /**
    * Returns lines currently in the log buffer without removing them
-   * @return {string} \n delimited log lines
+   * @return \n delimited log lines
    */
   public peekLogs(): string {
     return this.logs;
@@ -139,7 +139,7 @@ class IndexedDBLogStore {
   }
 
   /**
-   * @return {Promise} Resolves when the store is ready.
+   * @return Resolves when the store is ready.
    */
   public async connect(): Promise<void> {
     const req = this.indexedDB.open("logs");
@@ -219,7 +219,7 @@ class IndexedDBLogStore {
    * This guarantees that we will always eventually do a flush when flush() is
    * called.
    *
-   * @return {Promise} Resolved when the logs have been flushed.
+   * @return Resolved when the logs have been flushed.
    */
   public flush = async (): Promise<void> => {
     // check if a flush() operation is ongoing
@@ -270,7 +270,7 @@ class IndexedDBLogStore {
    * returned are deleted at the same time, so this can be called at startup
    * to do house-keeping to keep the logs from growing too large.
    *
-   * @return {Promise<Object[]>} Resolves to an array of objects. The array is
+   * @return Resolves to an array of objects. The array is
    * sorted in time (oldest first) based on when the log file was created (the
    * log ID). The objects have said log ID in an "id" field and "lines" which
    * is a big string with all the new-line delimited logs.
@@ -421,12 +421,12 @@ class IndexedDBLogStore {
 
 /**
  * Helper method to collect results from a Cursor and promiseify it.
- * @param {ObjectStore|Index} store The store to perform openCursor on.
- * @param {IDBKeyRange=} keyRange Optional key range to apply on the cursor.
- * @param {Function} resultMapper A function which is repeatedly called with a
+ * @param store - The store to perform openCursor on.
+ * @param keyRange - Optional key range to apply on the cursor.
+ * @param resultMapper - A function which is repeatedly called with a
  * Cursor.
  * Return the data you want to keep.
- * @return {Promise<T[]>} Resolves to an array of whatever you returned from
+ * @return Resolves to an array of whatever you returned from
  * resultMapper.
  */
 async function selectQuery<T>(
@@ -464,9 +464,7 @@ declare global {
 /**
  * Configure rage shaking support for sending bug reports.
  * Modifies globals.
- * @param {boolean} setUpPersistence When true (default), the persistence will
- * be set up immediately for the logs.
- * @return {Promise} Resolves when set up.
+ * @return Resolves when set up.
  */
 export async function init(): Promise<void> {
   global.mx_rage_logger = new ConsoleLogger();
@@ -503,7 +501,7 @@ export async function init(): Promise<void> {
 /**
  * Try to start up the rageshake storage for logs. If not possible (client unsupported)
  * then this no-ops.
- * @return {Promise} Resolves when complete.
+ * @return Resolves when complete.
  */
 async function tryInitStorage(): Promise<void> {
   if (global.mx_rage_initStoragePromise) {
@@ -536,7 +534,7 @@ async function tryInitStorage(): Promise<void> {
 /**
  * Get a recent snapshot of the logs, ready for attaching to a bug report
  *
- * @return {LogEntry[]}  list of log data
+ * @return list of log data
  */
 export async function getLogsForReport(): Promise<LogEntry[]> {
   if (!global.mx_rage_logger) {

src/state/CallViewModel/CallNotificationLifecycle.ts

@@ -81,7 +81,7 @@ export interface Props {
   localUser: { deviceId: string; userId: string };
 }
 /**
- * @returns {callPickupState$, autoLeave$}
+ * @returns two observables:
  * `callPickupState$` The current call pickup state of the call.
  *  - "unknown": The client has not yet sent the notification event. We don't know if it will because it first needs to send its own membership.
  *     Then we can conclude if we were the first one to join or not.

src/state/CallViewModel/localMember/LocalMember.ts

@@ -138,7 +138,16 @@ interface Props {
  * We want
  *  - a publisher
  *  -
- * @param param0
+ * @param props The properties required to create the local membership.
+ * @param props.scope The observable scope to use.
+ * @param props.connectionManager The connection manager to get connections from.
+ * @param props.createPublisherFactory Factory to create a publisher once we have a connection.
+ * @param props.joinMatrixRTC Callback to join the matrix RTC session once we have a transport.
+ * @param props.homeserverConnected The homeserver connected state.
+ * @param props.localTransport$ The local transport to use for publishing.
+ * @param props.logger The logger to use.
+ * @param props.muteStates The mute states for video and audio.
+ * @param props.matrixRTCSession The matrix RTC session to join.
  * @returns
  *  - publisher: The handle to create tracks and publish them to the room.
  *  - connected$: the current connection state. Including matrix server and livekit server connection. (only considering the livekit server we are using for our own media publication)
@@ -676,9 +685,11 @@ interface EnterRTCSessionOptions {
  *      - Delay events management
  *      - Handles retries (fails only after several attempts)
  *
- * @param rtcSession
- * @param transport
- * @param options
+ * @param rtcSession - The MatrixRTCSession to join.
+ * @param transport - The LivekitTransport to use for this session.
+ * @param options - Options for entering the RTC session.
+ * @param options.encryptMedia - Whether to encrypt media.
+ * @param options.matrixRTCMode - The Matrix RTC mode to use.
  * @throws If the widget could not send ElementWidgetActions.JoinCall action.
  */
 // Exported for unit testing

src/state/CallViewModel/localMember/Publisher.ts

@@ -143,7 +143,7 @@ export class Publisher {
     this.logger.debug("createAndSetupTracks called");
     const lkRoom = this.connection.livekitRoom;
     // Observe mute state changes and update LiveKit microphone/camera states accordingly
-    this.observeMuteStates(this.scope);
+    this.observeMuteStates();
 
     // Check if audio and/or video is enabled. We only create tracks if enabled,
     // because it could prompt for permission, and we don't want to do that unnecessarily.
@@ -356,10 +356,9 @@ export class Publisher {
 
   /**
    * Observe changes in the mute states and update the LiveKit room accordingly.
-   * @param scope
    * @private
    */
-  private observeMuteStates(scope: ObservableScope): void {
+  private observeMuteStates(): void {
     const lkRoom = this.connection.livekitRoom;
     this.muteStates.audio.setHandler(async (enable) => {
       try {

src/state/CallViewModel/remoteMembers/Connection.ts

@@ -218,7 +218,7 @@ export class Connection {
    *
    * @param opts - Connection options {@link ConnectionOpts}.
    *
-   * @param logger
+   * @param logger - The logger to use.
    */
   public constructor(opts: ConnectionOpts, logger: Logger) {
     this.logger = logger.getChild("[Connection]");

src/state/CallViewModel/remoteMembers/ConnectionFactory.ts

@@ -43,11 +43,11 @@ export class ECConnectionFactory implements ConnectionFactory {
    * @param client - The OpenID client parts for authentication, needed to get openID and JWT tokens.
    * @param devices - Used for video/audio out/in capture options.
    * @param processorState$ - Effects like background blur (only for publishing connection?)
-   * @param livekitKeyProvider
+   * @param livekitKeyProvider - Optional key provider for end-to-end encryption.
    * @param controlledAudioDevices - Option to indicate whether audio output device is controlled externally (native mobile app).
+   * @param livekitRoomFactory - Optional factory function (for testing) to create LivekitRoom instances. If not provided, a default factory is used.
    * @param echoCancellation - Whether to enable echo cancellation for audio capture.
    * @param noiseSuppression - Whether to enable noise suppression for audio capture.
-   * @param livekitRoomFactory - Optional factory function (for testing) to create LivekitRoom instances. If not provided, a default factory is used.
    */
   public constructor(
     private client: OpenIDClientParts,

src/state/CallViewModel/remoteMembers/ConnectionManager.ts

@@ -76,9 +76,11 @@ export interface IConnectionManager {
 
 /**
  * Crete a `ConnectionManager`
- * @param scope the observable scope used by this object.
- * @param connectionFactory used to create new connections.
- * @param _transportsSubscriptions$ A list of Behaviors each containing a LIST of LivekitTransport.
+ * @param props - Configuration object
+ * @param props.scope - The observable scope used by this object
+ * @param props.connectionFactory - Used to create new connections
+ * @param props.inputTransports$ - A list of Behaviors each containing a LIST of LivekitTransport.
+ * @param props.logger - The logger to use
  *   Each of these behaviors can be interpreted as subscribed list of transports.
  *
  *   Using `registerTransports` independent external modules can control what connections

src/useAudioContext.tsx

@@ -22,9 +22,12 @@ import * as controls from "./controls";
  * Play a sound though a given AudioContext. Will take
  * care of connecting the correct buffer and gating
  * through gain.
- * @param volume The volume to play at.
  * @param ctx The context to play through.
  * @param buffer The buffer to play.
+ * @param volume The volume to play at.
+ * @param stereoPan The stereo pan to apply.
+ * @param delayS Delay in seconds before starting playing.
+ * @param abort Optional AbortController that can be used to stop playback.
  * @returns A promise that resolves when the sound has finished playing.
  */
 async function playSound(
@@ -55,9 +58,11 @@ async function playSound(
  * Play a sound though a given AudioContext, looping until stopped. Will take
  * care of connecting the correct buffer and gating
  * through gain.
- * @param volume The volume to play at.
  * @param ctx The context to play through.
  * @param buffer The buffer to play.
+ * @param volume The volume to play at.
+ * @param stereoPan The stereo pan to apply.
+ * @param delayS Delay in seconds between each loop.
  * @returns A function used to end the sound. This function will return a promise when the sound has stopped.
  */
 function playSoundLooping(
@@ -120,7 +125,7 @@ interface UseAudioContext<S extends string> {
 /**
  * Add an audio context which can be used to play
  * a set of preloaded sounds.
- * @param props
+ * @param props The properties for the audio context.
  * @returns Either an instance that can be used to play sounds, or null if not ready.
  */
 export function useAudioContext<S extends string>(

src/utils/displayname.ts

@@ -77,6 +77,13 @@ export function shouldDisambiguate(
   );
 }
 
+/**
+ * Calculates a display name for a member, optionally disambiguating it.
+ * @param member - The member to calculate the display name for.
+ * @param member.rawDisplayName - The raw display name of the member
+ * @param member.userId - The user ID of the member
+ * @param disambiguate - Whether to disambiguate the display name.
+ */
 export function calculateDisplayName(
   member: { rawDisplayName?: string; userId: string },
   disambiguate: boolean,

src/utils/errors.ts

@@ -57,9 +57,16 @@ export class ElementCallError extends Error {
   }
 }
 
+/**
+ * Configuration problem due to no MatrixRTC backend/SFU is exposed via .well-known and no fallback configured.
+ */
 export class MatrixRTCTransportMissingError extends ElementCallError {
   public domain: string;
 
+  /**
+   * Creates an instance of MatrixRTCTransportMissingError.
+   * @param domain - The domain where the MatrixRTC transport is missing.
+   */
   public constructor(domain: string) {
     super(
       t("error.call_is_not_supported"),
@@ -75,7 +82,11 @@ export class MatrixRTCTransportMissingError extends ElementCallError {
   }
 }
 
+/**
+ * Error indicating that the connection to the call was lost and could not be re-established.
+ */
 export class ConnectionLostError extends ElementCallError {
+
   public constructor() {
     super(
       t("error.connection_lost"),
@@ -86,7 +97,17 @@ export class ConnectionLostError extends ElementCallError {
   }
 }
 
+/**
+ * Error indicating a failure in the membership manager causing the join call
+ * operation to fail.
+ */
 export class MembershipManagerError extends ElementCallError {
+
+  /**
+   * Creates an instance of MembershipManagerError.
+   *
+   * @param error - The underlying error that caused the membership manager failure.
+   */
   public constructor(error: Error) {
     super(
       t("error.membership_manager"),
@@ -98,7 +119,11 @@ export class MembershipManagerError extends ElementCallError {
   }
 }
 
+/**
+ * Error indicating that end-to-end encryption is not supported in the current environment.
+ */
 export class E2EENotSupportedError extends ElementCallError {
+
   public constructor() {
     super(
       t("error.e2ee_unsupported"),
@@ -109,7 +134,15 @@ export class E2EENotSupportedError extends ElementCallError {
   }
 }
 
+/**
+ * Error indicating an unknown issue occurred during a call operation.
+ */
 export class UnknownCallError extends ElementCallError {
+
+  /**
+   * Creates an instance of UnknownCallError.
+   * @param error - The underlying error that caused the unknown issue.
+   */
   public constructor(error: Error) {
     super(
       t("error.generic"),
@@ -122,7 +155,14 @@ export class UnknownCallError extends ElementCallError {
   }
 }
 
+/**
+ * Error indicating a failure to obtain an OpenID token.
+ */
 export class FailToGetOpenIdToken extends ElementCallError {
+  /**
+   * Creates an instance of FailToGetOpenIdToken.
+   * @param error - The underlying error that caused the failure.
+   */
   public constructor(error: Error) {
     super(
       t("error.generic"),
@@ -135,7 +175,15 @@ export class FailToGetOpenIdToken extends ElementCallError {
   }
 }
 
+/**
+ * Error indicating a failure to start publishing on a LiveKit connection.
+ */
 export class FailToStartLivekitConnection extends ElementCallError {
+
+  /**
+   * Creates an instance of FailToStartLivekitConnection.
+   * @param e - An optional error message providing additional context.
+   */
   public constructor(e?: string) {
     super(
       t("error.failed_to_start_livekit"),
@@ -146,6 +194,9 @@ export class FailToStartLivekitConnection extends ElementCallError {
   }
 }
 
+/**
+ * Error indicating that a LiveKit's server has hit its track limits.
+ */
 export class InsufficientCapacityError extends ElementCallError {
   public constructor() {
     super(
@@ -157,6 +208,10 @@ export class InsufficientCapacityError extends ElementCallError {
   }
 }
 
+/**
+ * Error indicating that room creation is restricted by the SFU.
+ * Only authorized users can create rooms, so the room must exist before connecting (done by the auth jwt service)
+ */
 export class SFURoomCreationRestrictedError extends ElementCallError {
   public constructor() {
     super(

src/utils/matrix.ts

@@ -188,7 +188,6 @@ function fullAliasFromRoomName(roomName: string, client: MatrixClient): string {
  * Applies some basic sanitisation to a room name that the user
  * has given us
  * @param input The room name from the user
- * @param client A matrix client object
  */
 export function sanitiseRoomNameInput(input: string): string {
   // check to see if the user has entered a fully qualified room
@@ -304,8 +303,9 @@ export async function createRoom(
 /**
  * Returns an absolute URL to that will load Element Call with the given room
  * @param roomId ID of the room
- * @param roomName Name of the room
  * @param encryptionSystem what encryption (or EncryptionSystem.Unencrypted) the room uses
+ * @param roomName Name of the room
+ * @param viaServers Optional list of servers to include as 'via' parameters in the URL
  */
 export function getAbsoluteRoomUrl(
   roomId: string,
@@ -321,8 +321,9 @@ export function getAbsoluteRoomUrl(
 /**
  * Returns a relative URL to that will load Element Call with the given room
  * @param roomId ID of the room
- * @param roomName Name of the room
  * @param encryptionSystem what encryption (or EncryptionSystem.Unencrypted) the room uses
+ * @param roomName Name of the room
+ * @param viaServers Optional list of servers to include as 'via' parameters in the URL
  */
 export function getRelativeRoomUrl(
   roomId: string,

src/utils/media.ts

@@ -8,6 +8,7 @@ Please see LICENSE in the repository root for full details.
 /**
  * Finds a media device with label matching 'deviceName'
  * @param deviceName The label of the device to look for
+ * @param kind The kind of media device to look for
  * @param devices The list of devices to search
  * @returns A matching media device or undefined if no matching device was found
  */

src/utils/observable.ts

@@ -135,7 +135,6 @@ interface ItemHandle<Data, Item> {
  * requested at a later time, and destroyed (have their scope ended) when the
  * key is no longer requested.
  *
- * @param input$ The input value to be mapped.
  * @param generator A generator function yielding a tuple of keys and the
  *   currently associated data for each item that it wants to exist.
  * @param factory A function constructing an individual item, given the item's key,