docs(websocket): add JSDoc documentation

apps/api/src/websocket/websocket.gateway.ts

@@ -33,8 +33,7 @@ interface Project {
 }
 
 /**
- * WebSocket Gateway for real-time updates
- * Handles workspace-scoped rooms for broadcasting events
+ * @description WebSocket Gateway for real-time updates. Handles workspace-scoped rooms for broadcasting events.
  */
 @WSGateway({
   cors: {
@@ -49,8 +48,9 @@ export class WebSocketGateway implements OnGatewayConnection, OnGatewayDisconnec
   private readonly logger = new Logger(WebSocketGateway.name);
 
   /**
-   * Handle client connection
-   * Joins client to workspace-specific room
+   * @description Handle client connection by authenticating and joining the workspace-specific room.
+   * @param client - The authenticated socket client containing userId and workspaceId in data.
+   * @returns Promise that resolves when the client is joined to the workspace room or disconnected.
    */
   async handleConnection(client: AuthenticatedSocket): Promise<void> {
     const { userId, workspaceId } = client.data;
@@ -68,8 +68,9 @@ export class WebSocketGateway implements OnGatewayConnection, OnGatewayDisconnec
   }
 
   /**
-   * Handle client disconnect
-   * Leaves workspace room
+   * @description Handle client disconnect by leaving the workspace room.
+   * @param client - The socket client containing workspaceId in data.
+   * @returns void
    */
   handleDisconnect(client: AuthenticatedSocket): void {
     const { workspaceId } = client.data;
@@ -82,7 +83,10 @@ export class WebSocketGateway implements OnGatewayConnection, OnGatewayDisconnec
   }
 
   /**
-   * Emit task:created event to workspace room
+   * @description Emit task:created event to all clients in the workspace room.
+   * @param workspaceId - The workspace identifier for the room to broadcast to.
+   * @param task - The task object that was created.
+   * @returns void
    */
   emitTaskCreated(workspaceId: string, task: Task): void {
     const room = this.getWorkspaceRoom(workspaceId);
@@ -91,7 +95,10 @@ export class WebSocketGateway implements OnGatewayConnection, OnGatewayDisconnec
   }
 
   /**
-   * Emit task:updated event to workspace room
+   * @description Emit task:updated event to all clients in the workspace room.
+   * @param workspaceId - The workspace identifier for the room to broadcast to.
+   * @param task - The task object that was updated.
+   * @returns void
    */
   emitTaskUpdated(workspaceId: string, task: Task): void {
     const room = this.getWorkspaceRoom(workspaceId);
@@ -100,7 +107,10 @@ export class WebSocketGateway implements OnGatewayConnection, OnGatewayDisconnec
   }
 
   /**
-   * Emit task:deleted event to workspace room
+   * @description Emit task:deleted event to all clients in the workspace room.
+   * @param workspaceId - The workspace identifier for the room to broadcast to.
+   * @param taskId - The ID of the task that was deleted.
+   * @returns void
    */
   emitTaskDeleted(workspaceId: string, taskId: string): void {
     const room = this.getWorkspaceRoom(workspaceId);
@@ -109,7 +119,10 @@ export class WebSocketGateway implements OnGatewayConnection, OnGatewayDisconnec
   }
 
   /**
-   * Emit event:created event to workspace room
+   * @description Emit event:created event to all clients in the workspace room.
+   * @param workspaceId - The workspace identifier for the room to broadcast to.
+   * @param event - The event object that was created.
+   * @returns void
    */
   emitEventCreated(workspaceId: string, event: Event): void {
     const room = this.getWorkspaceRoom(workspaceId);
@@ -118,7 +131,10 @@ export class WebSocketGateway implements OnGatewayConnection, OnGatewayDisconnec
   }
 
   /**
-   * Emit event:updated event to workspace room
+   * @description Emit event:updated event to all clients in the workspace room.
+   * @param workspaceId - The workspace identifier for the room to broadcast to.
+   * @param event - The event object that was updated.
+   * @returns void
    */
   emitEventUpdated(workspaceId: string, event: Event): void {
     const room = this.getWorkspaceRoom(workspaceId);
@@ -127,7 +143,10 @@ export class WebSocketGateway implements OnGatewayConnection, OnGatewayDisconnec
   }
 
   /**
-   * Emit event:deleted event to workspace room
+   * @description Emit event:deleted event to all clients in the workspace room.
+   * @param workspaceId - The workspace identifier for the room to broadcast to.
+   * @param eventId - The ID of the event that was deleted.
+   * @returns void
    */
   emitEventDeleted(workspaceId: string, eventId: string): void {
     const room = this.getWorkspaceRoom(workspaceId);
@@ -136,7 +155,10 @@ export class WebSocketGateway implements OnGatewayConnection, OnGatewayDisconnec
   }
 
   /**
-   * Emit project:created event to workspace room
+   * @description Emit project:created event to all clients in the workspace room.
+   * @param workspaceId - The workspace identifier for the room to broadcast to.
+   * @param project - The project object that was created.
+   * @returns void
    */
   emitProjectCreated(workspaceId: string, project: Project): void {
     const room = this.getWorkspaceRoom(workspaceId);
@@ -145,7 +167,10 @@ export class WebSocketGateway implements OnGatewayConnection, OnGatewayDisconnec
   }
 
   /**
-   * Emit project:updated event to workspace room
+   * @description Emit project:updated event to all clients in the workspace room.
+   * @param workspaceId - The workspace identifier for the room to broadcast to.
+   * @param project - The project object that was updated.
+   * @returns void
    */
   emitProjectUpdated(workspaceId: string, project: Project): void {
     const room = this.getWorkspaceRoom(workspaceId);
@@ -154,7 +179,10 @@ export class WebSocketGateway implements OnGatewayConnection, OnGatewayDisconnec
   }
 
   /**
-   * Emit project:deleted event to workspace room
+   * @description Emit project:deleted event to all clients in the workspace room.
+   * @param workspaceId - The workspace identifier for the room to broadcast to.
+   * @param projectId - The ID of the project that was deleted.
+   * @returns void
    */
   emitProjectDeleted(workspaceId: string, projectId: string): void {
     const room = this.getWorkspaceRoom(workspaceId);
@@ -163,7 +191,9 @@ export class WebSocketGateway implements OnGatewayConnection, OnGatewayDisconnec
   }
 
   /**
-   * Get workspace room name
+   * @description Get workspace room name for Socket.IO room management.
+   * @param workspaceId - The workspace identifier.
+   * @returns The room name in format "workspace:{workspaceId}".
    */
   private getWorkspaceRoom(workspaceId: string): string {
     return `workspace:${workspaceId}`;