From 511d1a11d5b6895c088795b2effff1602dd0cf9a Mon Sep 17 00:00:00 2001
From: Nightt <87569709+nightt5879@users.noreply.github.com>
Date: Wed, 24 Jun 2026 18:40:42 +0800
Subject: [PATCH] docs: document main namespace shortcuts

---
 packages/socket.io/lib/index.ts | 28 ++++++++++++++++++++++++++++
 1 file changed, 28 insertions(+)

diff --git a/packages/socket.io/lib/index.ts b/packages/socket.io/lib/index.ts
index 0cebc92544..b2996ef879 100644
--- a/packages/socket.io/lib/index.ts
+++ b/packages/socket.io/lib/index.ts
@@ -128,6 +128,21 @@ interface ServerOptions extends EngineOptions, AttachOptions {
  *
  * const io = new Server();
  *
+ * The server exposes the main namespace (`"/"`) through a set of shorthand
+ * methods. For example, `io.on("connection")`, `io.use(...)` and
+ * `io.emit(...)` are equivalent to calling `io.of("/")` and then the
+ * corresponding {@link Namespace} method.
+ *
+ * @example
+ * io.on("connection", (socket) => {});
+ * io.use((socket, next) => { next(); });
+ * io.emit("hello");
+ *
+ * // are equivalent to:
+ * io.of("/").on("connection", (socket) => {});
+ * io.of("/").use((socket, next) => { next(); });
+ * io.of("/").emit("hello");
+ *
  * io.on("connection", (socket) => {
  *   console.log(`socket ${socket.id} connected`);
  *
@@ -220,6 +235,19 @@ export class Server<
     SocketData
   >
 > {
+  /**
+   * The main namespace, named `"/"`.
+   *
+   * Most namespace-level methods exposed by {@link Server}, such as
+   * `on("connection")`, `use()`, `emit()`, `to()`, `in()` and `except()`, are
+   * shortcuts for calling the same methods on this namespace.
+   *
+   * @example
+   * io.sockets.emit("hello");
+   *
+   * // is equivalent to:
+   * io.emit("hello");
+   */
   public readonly sockets: Namespace<
     ListenEvents,
     EmitEvents,