docs(engine.io): improve JSDoc completeness in server.ts

packages/engine.io/lib/server.ts

@@ -237,9 +237,11 @@ export abstract class BaseServer extends EventEmitter {
   protected abstract init(): void;
 
   /**
-   * Compute the pathname of the requests that are handled by the server
+   * Compute the pathname of the requests that are handled by the server.
+   * 
    * @param options
    * @protected
+   * @returns {string} the normalized request path
    */
   protected _computePath(options: AttachOptions) {
     let path = (options.path || "/engine.io").replace(/\/$/, "");
@@ -422,12 +424,12 @@ export abstract class BaseServer extends EventEmitter {
   }
 
   /**
-   * Handshakes a new client.
-   *
-   * @param {String} transportName
-   * @param {Object} req - the request object
-   * @param {Function} closeConnection
+   * Performs the Engine.IO handshake for a new client.
    *
+   * @param {TransportName} transportName - the selected transport
+   * @param {EngineRequest} req - the incoming request
+   * @param {ErrorCallback} closeConnection - callback used to close the connection with an error
+   * @returns {Promise<void>}
    * @protected
    */
   protected async handshake(
@@ -524,7 +526,14 @@ export abstract class BaseServer extends EventEmitter {
 
     return transport;
   }
-
+
+  /**
+   * Handles a WebTransport session and performs the necessary handshake logic.
+   *
+   * @param {any} session - the WebTransport session object
+   * @returns {Promise<void>}
+   * @protected
+  */
   public async onWebTransportSession(session: any) {
     const timeout = setTimeout(() => {
       debug(
@@ -682,7 +691,7 @@ export class Server extends BaseServer {
   private ws: WsServer;
 
   /**
-   * Initialize websocket server
+   * Initializes the WebSocket server, if the "websocket" transport is enabled.
    *
    * @protected
    */
@@ -842,10 +851,12 @@ export class Server extends BaseServer {
   }
 
   /**
-   * Called upon a ws.io connection.
-   * @param req
-   * @param socket
-   * @param websocket
+   * Handles an incoming WebSocket upgrade and attaches the appropriate transport.
+   * 
+   * @param {EngineRequest} req - the request object
+   * @param {Duplex} socket - the raw TCP socket
+   * @param {WsWebSocket} websocket - the WebSocket instance
+   * @returns {void}
    * @private
    */
   private onWebSocket(
@@ -912,10 +923,12 @@ export class Server extends BaseServer {
   }
 
   /**
-   * Captures upgrade requests for a http.Server.
+   * Captures upgrade requests for a Node.js HTTP server and forwards them
+   * to the Engine.IO request and upgrade handlers.
    *
-   * @param {http.Server} server
-   * @param {Object} options
+   * @param {HttpServer} server - the underlying Node.js HTTP server
+   * @param {AttachOptions} options - configuration options
+   * @returns {void}
    */
   public attach(server: HttpServer, options: AttachOptions = {}) {
     const path = this._computePath(options);
@@ -971,12 +984,12 @@ export class Server extends BaseServer {
 }
 
 /**
- * Close the HTTP long-polling request
- *
- * @param res - the response object
- * @param errorCode - the error code
- * @param errorContext - additional error context
+ * Closes the HTTP long-polling request with an error response.
  *
+ * @param {ServerResponse} res - the response object
+ * @param {number} errorCode - the error code
+ * @param {{ message?: string }} errorContext - additional error context
+ * @returns {void}
  * @private
  */
 
@@ -1004,7 +1017,7 @@ function abortRequest(
  * Close the WebSocket connection
  *
  * @param {net.Socket} socket
- * @param {string} errorCode - the error code
+ * @param {number} errorCode - the error code
  * @param {object} errorContext - additional error context
  */
 

packages/engine.io/lib/socket.ts

@@ -89,16 +89,16 @@ export class Socket extends EventEmitter {
     this.request = req;
     this.protocol = protocol;
 
-    // Cache IP since it might not be in the req later
+    // Cache IP since it might not be in the request later
     if (req) {
       if (req.websocket && req.websocket._socket) {
         this.remoteAddress = req.websocket._socket.remoteAddress;
       } else {
         this.remoteAddress = req.connection.remoteAddress;
       }
     } else {
-      // TODO there is currently no way to get the IP address of the client when it connects with WebTransport
-      //  see https://github.com/fails-components/webtransport/issues/114
+      // TODO: There is currently no way to get the IP address of the client when it connects with WebTransport.
+      // See https://github.com/fails-components/webtransport/issues/114
     }
 
     this.pingTimeoutTimer = null;
@@ -195,7 +195,7 @@ export class Socket extends EventEmitter {
   /**
    * Called upon transport error.
    *
-   * @param {Error} err - error object
+   * @param {Error} err - The error object.
    * @private
    */
   private onError(err: Error) {
@@ -268,7 +268,7 @@ export class Socket extends EventEmitter {
   }
 
   /**
-   * Upon transport "drain" event
+   * Upon transport "drain" event.
    *
    * @private
    */
@@ -337,7 +337,7 @@ export class Socket extends EventEmitter {
       }
     };
 
-    // we force a polling cycle to ensure a fast upgrade
+    // We force a polling cycle to ensure a fast upgrade.
     const check = () => {
       if ("polling" === this.transport.name && this.transport.writable) {
         debug("writing a noop packet to polling for fast upgrade");
@@ -394,12 +394,12 @@ export class Socket extends EventEmitter {
       cleanup();
     }
 
-    // silence further transport errors and prevent uncaught exceptions
+    // silence further transport errors and prevent uncaught exceptions.
     this.transport.on("error", function () {
       debug("error triggered by discarded transport");
     });
 
-    // ensure transport won't stay open
+    // ensure transport won't stay open.
     this.transport.close();
 
     clearTimeout(this.pingTimeoutTimer);
@@ -414,12 +414,12 @@ export class Socket extends EventEmitter {
     if ("closed" !== this.readyState) {
       this.readyState = "closed";
 
-      // clear timers
+      // Clear timers.
       clearTimeout(this.pingIntervalTimer);
       clearTimeout(this.pingTimeoutTimer);
 
-      // clean writeBuffer in next tick, so developers can still
-      // grab the writeBuffer on 'close' event
+      // Clean writeBuffer in next tick, so developers can still
+      // grab the writeBuffer on the "close" event.
       process.nextTick(() => {
         this.writeBuffer = [];
       });
@@ -489,7 +489,7 @@ export class Socket extends EventEmitter {
 
       if (data) packet.data = data;
 
-      // exports packetCreate event
+      // Export packetCreate event.
       this.emit("packetCreate", packet);
 
       this.writeBuffer.push(packet);

packages/engine.io/lib/transports/websocket.ts

@@ -10,7 +10,7 @@ export class WebSocket extends Transport {
   private socket: WsWebSocket;
 
   /**
-   * WebSocket transport
+   * WebSocket transport.
    *
    * @param {EngineRequest} req
    */
@@ -50,8 +50,8 @@ export class WebSocket extends Transport {
       const isLast = i + 1 === packets.length;
 
       if (this._canSendPreEncodedFrame(packet)) {
-        // the WebSocket frame was computed with WebSocket.Sender.frame()
-        // see https://github.com/websockets/ws/issues/617#issuecomment-283002469
+        // The WebSocket frame was computed with WebSocket.Sender.frame().
+        // See https://github.com/websockets/ws/issues/617#issuecomment-283002469
         // @ts-expect-error use of untyped member
         this.socket._sender.sendFrame(
           packet.options.wsPreEncodedFrame,