docs: add some jsdoc for each public method

Author: darrachequesne

mod.ts

@@ -1,3 +1,30 @@
+/**
+ * @example
+ * import { serve } from "https://deno.land/[email protected]/http/server.ts";
+ * import { Server } from "https://deno.land/x/[email protected]/mod.ts";
+ *
+ * const io = new Server();
+ *
+ * io.on("connection", (socket) => {
+ *   console.log(`socket ${socket.id} connected`);
+ *
+ *   // send an event to the client
+ *   socket.emit("foo", "bar");
+ *
+ *   socket.on("foobar", () => {
+ *     // an event was received from the client
+ *   });
+ *
+ *   // upon disconnection
+ *   socket.on("disconnect", (reason) => {
+ *     console.log(`socket ${socket.id} disconnected due to ${reason}`);
+ *   });
+ * });
+ *
+ * await serve(io.handler(), {
+ *   port: 3000,
+ * });
+ */
 export {
   Adapter,
   type BroadcastOptions,
@@ -12,9 +39,7 @@ export {
  *
  * Documentation: https://socket.io/docs/v4/redis-adapter/
  *
- * Usage:
- *
- * ```
+ * @example
  * import { serve } from "https://deno.land/std/http/server.ts";
  * import { Server, createRedisAdapter, createRedisClient } from "https://deno.land/x/socket_io/mod.ts";
  *
@@ -34,7 +59,6 @@ export {
  * await serve(io.handler(), {
  *     port: 3000
  * });
- * ```
  */
 export {
   createAdapter as createRedisAdapter,

packages/socket.io/lib/broadcast-operator.ts

@@ -26,8 +26,18 @@ export class BroadcastOperator<EmitEvents extends EventsMap, SocketData>
   /**
    * Targets a room when emitting.
    *
-   * @param room
-   * @return a new BroadcastOperator instance
+   * @example
+   * // the “foo” event will be broadcast to all connected clients in the “room-101” room
+   * io.to("room-101").emit("foo", "bar");
+   *
+   * // with an array of rooms (a client will be notified at most once)
+   * io.to(["room-101", "room-102"]).emit("foo", "bar");
+   *
+   * // with multiple chained calls
+   * io.to("room-101").to("room-102").emit("foo", "bar");
+   *
+   * @param room - a room, or an array of rooms
+   * @return a new {@link BroadcastOperator} instance for chaining
    */
   public to(room: Room | Room[]): BroadcastOperator<EmitEvents, SocketData> {
     const rooms = new Set(this.rooms);
@@ -45,10 +55,14 @@ export class BroadcastOperator<EmitEvents extends EventsMap, SocketData>
   }
 
   /**
-   * Targets a room when emitting.
+   * Targets a room when emitting. Similar to `to()`, but might feel clearer in some cases:
    *
-   * @param room
-   * @return a new BroadcastOperator instance
+   * @example
+   * // disconnect all clients in the "room-101" room
+   * io.in("room-101").disconnectSockets();
+   *
+   * @param room - a room, or an array of rooms
+   * @return a new {@link BroadcastOperator} instance for chaining
    */
   public in(room: Room | Room[]): BroadcastOperator<EmitEvents, SocketData> {
     return this.to(room);
@@ -57,8 +71,18 @@ export class BroadcastOperator<EmitEvents extends EventsMap, SocketData>
   /**
    * Excludes a room when emitting.
    *
-   * @param room
-   * @return a new BroadcastOperator instance
+   * @example
+   * // the "foo" event will be broadcast to all connected clients, except the ones that are in the "room-101" room
+   * io.except("room-101").emit("foo", "bar");
+   *
+   * // with an array of rooms
+   * io.except(["room-101", "room-102"]).emit("foo", "bar");
+   *
+   * // with multiple chained calls
+   * io.except("room-101").except("room-102").emit("foo", "bar");
+   *
+   * @param room - a room, or an array of rooms
+   * @return a new {@link BroadcastOperator} instance for chaining
    */
   public except(
     room: Room | Room[],
@@ -82,7 +106,10 @@ export class BroadcastOperator<EmitEvents extends EventsMap, SocketData>
    * receive messages (because of network slowness or other issues, or because they’re connected through long polling
    * and is in the middle of a request-response cycle).
    *
-   * @return a new BroadcastOperator instance
+   * @example
+   * io.volatile.emit("hello"); // the clients may or may not receive it
+   *
+   * @return a new {@link BroadcastOperator} instance for chaining
    */
   public get volatile(): BroadcastOperator<EmitEvents, SocketData> {
     const flags = Object.assign({}, this.flags, { volatile: true });
@@ -97,7 +124,11 @@ export class BroadcastOperator<EmitEvents extends EventsMap, SocketData>
   /**
    * Sets a modifier for a subsequent event emission that the event data will only be broadcast to the current node.
    *
-   * @return a new BroadcastOperator instance
+   * @example
+   * // the “foo” event will be broadcast to all connected clients on this node
+   * io.local.emit("foo", "bar");
+   *
+   * @return a new {@link BroadcastOperator} instance for chaining
    */
   public get local(): BroadcastOperator<EmitEvents, SocketData> {
     const flags = Object.assign({}, this.flags, { local: true });
@@ -112,14 +143,15 @@ export class BroadcastOperator<EmitEvents extends EventsMap, SocketData>
   /**
    * Adds a timeout in milliseconds for the next operation
    *
-   * <pre><code>
-   *
+   * @example
    * io.timeout(1000).emit("some-event", (err, responses) => {
-   *   // ...
+   *   if (err) {
+   *     // some clients did not acknowledge the event in the given delay
+   *   } else {
+   *     console.log(responses); // one response per client
+   *   }
    * });
    *
-   * </pre></code>
-   *
    * @param timeout
    */
   public timeout(timeout: number) {
@@ -135,6 +167,22 @@ export class BroadcastOperator<EmitEvents extends EventsMap, SocketData>
   /**
    * Emits to all clients.
    *
+   * @example
+   * // the “foo” event will be broadcast to all connected clients
+   * io.emit("foo", "bar");
+   *
+   * // the “foo” event will be broadcast to all connected clients in the “room-101” room
+   * io.to("room-101").emit("foo", "bar");
+   *
+   * // with an acknowledgement expected from all connected clients
+   * io.timeout(1000).emit("some-event", (err, responses) => {
+   *   if (err) {
+   *     // some clients did not acknowledge the event in the given delay
+   *   } else {
+   *     console.log(responses); // one response per client
+   *   }
+   * });
+   *
    * @return Always true
    */
   public emit<Ev extends EventNames<EmitEvents>>(
@@ -218,7 +266,26 @@ export class BroadcastOperator<EmitEvents extends EventsMap, SocketData>
   }
 
   /**
-   * Returns the matching socket instances
+   * Returns the matching socket instances. This method works across a cluster of several Socket.IO servers.
+   *
+   * @example
+   * // return all Socket instances
+   * const sockets = await io.fetchSockets();
+   *
+   * // return all Socket instances in the "room1" room
+   * const sockets = await io.in("room1").fetchSockets();
+   *
+   * for (const socket of sockets) {
+   *   console.log(socket.id);
+   *   console.log(socket.handshake);
+   *   console.log(socket.rooms);
+   *   console.log(socket.data);
+   *
+   *   socket.emit("hello");
+   *   socket.join("room1");
+   *   socket.leave("room2");
+   *   socket.disconnect();
+   * }
    */
   public fetchSockets<SocketData = unknown>(): Promise<
     RemoteSocket<EmitEvents, SocketData>[]
@@ -245,9 +312,19 @@ export class BroadcastOperator<EmitEvents extends EventsMap, SocketData>
   }
 
   /**
-   * Makes the matching socket instances join the specified rooms
+   * Makes the matching socket instances join the specified rooms.
+   *
+   * Note: this method also works within a cluster of multiple Socket.IO servers, with a compatible {@link Adapter}.
+   *
+   * @example
+   *
+   * // make all socket instances join the "room1" room
+   * io.socketsJoin("room1");
    *
-   * @param room
+   * // make all socket instances in the "room1" room join the "room2" and "room3" rooms
+   * io.in("room1").socketsJoin(["room2", "room3"]);
+   *
+   * @param room - a room, or an array of rooms
    */
   public socketsJoin(room: Room | Room[]): void {
     this.adapter.addSockets(
@@ -261,9 +338,18 @@ export class BroadcastOperator<EmitEvents extends EventsMap, SocketData>
   }
 
   /**
-   * Makes the matching socket instances leave the specified rooms
+   * Makes the matching socket instances leave the specified rooms.
+   *
+   * Note: this method also works within a cluster of multiple Socket.IO servers, with a compatible {@link Adapter}.
+   *
+   * @example
+   * // make all socket instances leave the "room1" room
+   * io.socketsLeave("room1");
+   *
+   * // make all socket instances in the "room1" room leave the "room2" and "room3" rooms
+   * io.in("room1").socketsLeave(["room2", "room3"]);
    *
-   * @param room
+   * @param room - a room, or an array of rooms
    */
   public socketsLeave(room: Room | Room[]): void {
     this.adapter.delSockets(
@@ -277,7 +363,16 @@ export class BroadcastOperator<EmitEvents extends EventsMap, SocketData>
   }
 
   /**
-   * Makes the matching socket instances disconnect
+   * Makes the matching socket instances disconnect.
+   *
+   * Note: this method also works within a cluster of multiple Socket.IO servers, with a compatible {@link Adapter}.
+   *
+   * @example
+   * // make all socket instances disconnect (the connections might be kept alive for other namespaces)
+   * io.disconnectSockets();
+   *
+   * // make all socket instances in the "room1" room disconnect and close the underlying connections
+   * io.in("room1").disconnectSockets(true);
    *
    * @param close - whether to close the underlying connection
    */

packages/socket.io/lib/client.ts

@@ -11,6 +11,9 @@ interface WriteOptions {
   volatile?: boolean;
 }
 
+/**
+ * A {@link Client} can be associated with many multiplexed {@link Socket} that belong to different {@link Namespace}.
+ */
 export class Client<
   ListenEvents extends EventsMap,
   EmitEvents extends EventsMap,