📝 Add docstrings to binary-eio-v3

netty-socketio-core/src/main/java/com/socketio4j/socketio/SingleRoomBroadcastOperations.java

@@ -58,6 +58,11 @@ public Collection<SocketIOClient> getClients() {
         return new IterableCollection<>(clients);
     }
 
+    /**
+     * Sends a packet to every client in the room and dispatches it to the event store.
+     *
+     * @param packet the packet to send
+     */
     @Override
     public void send(Packet packet) {
         for (SocketIOClient client : clients) {
@@ -89,6 +94,13 @@ public void sendEvent(String name, SocketIOClient excludedClient, Object... data
         sendEvent(name, excludePredicate, data);
     }
 
+    /**
+     * Sends a named event with the specified data to clients that do not match the exclusion predicate.
+     *
+     * @param name            the event name
+     * @param excludePredicate the predicate identifying clients to exclude
+     * @param data            the event data
+     */
     @Override
     public void sendEvent(String name, Predicate<SocketIOClient> excludePredicate, Object... data) {
         Packet packet = new Packet(PacketType.MESSAGE, EngineIOVersion.UNKNOWN);

netty-socketio-core/src/main/java/com/socketio4j/socketio/SocketIOServer.java

@@ -1068,11 +1068,21 @@ public void addConnectListener(ConnectListener listener) {
         mainNamespace.addConnectListener(listener);
     }
 
+    /**
+     * Removes a listener invoked when a client connects.
+     *
+     * @param listener the connection listener to remove
+     */
     @Override
     public void removeConnectListener(ConnectListener listener) {
         mainNamespace.removeConnectListener(listener);
     }
 
+    /**
+     * Removes a disconnect listener from the main namespace.
+     *
+     * @param listener the disconnect listener to remove
+     */
     @Override
     public void removeDisconnectListener(DisconnectListener listener) {
         mainNamespace.removeDisconnectListener(listener);

netty-socketio-core/src/main/java/com/socketio4j/socketio/handler/EncoderHandler.java

@@ -266,6 +266,18 @@ public void write(ChannelHandlerContext ctx, Object msg, ChannelPromise promise)
     private static final int FRAME_BUFFER_SIZE = 8192;
 
 
+    /**
+     * Encodes and sends queued packets and attachments as WebSocket frames.
+     *
+     * <p>Large packet payloads are fragmented according to the configured maximum frame
+     * payload length. Attachment frames include the Engine.IO v2 or v3 prefix when
+     * required, and the supplied promise is completed after queued writes finish.</p>
+     *
+     * @param msg     the outbound packet message containing the client packet queue
+     * @param ctx     the channel handler context used for encoding and writing frames
+     * @param promise the promise completed when processing finishes
+     * @throws IOException if packet encoding fails
+     */
     private void handleWebsocket(final OutPacketMessage msg, ChannelHandlerContext ctx, ChannelPromise promise) throws IOException {
         if (log.isDebugEnabled()) {
             log.debug("Starting WebSocket message processing, sessionId: {}", msg.getSessionId());
@@ -352,6 +364,14 @@ private void handleWebsocket(final OutPacketMessage msg, ChannelHandlerContext c
         }
     }
 
+    /**
+     * Encodes and sends queued packets as an HTTP polling response.
+     *
+     * <p>Processes one response per channel and selects the response encoding and content type
+     * according to the Engine.IO version and queued packet content.</p>
+     *
+     * @throws IOException if packet encoding fails
+     */
     private void handleHTTP(OutPacketMessage msg, ChannelHandlerContext ctx, ChannelPromise promise) throws IOException {
         if (log.isDebugEnabled()) {
             log.debug("Starting HTTP polling message processing, sessionId: {}", msg.getSessionId());

netty-socketio-core/src/main/java/com/socketio4j/socketio/handler/InPacketHandler.java

@@ -58,6 +58,12 @@ public InPacketHandler(PacketListener packetListener, PacketDecoder decoder, Nam
         this.exceptionListener = exceptionListener;
     }
 
+    /**
+     * Processes inbound packets for a client and dispatches them to the appropriate namespace.
+     *
+     * @param message the inbound packet message containing the payload, client, and transport
+     * @throws Exception if packet decoding or processing fails
+     */
     @Override
     protected void channelRead0(io.netty.channel.ChannelHandlerContext ctx, PacketsMessage message)
                 throws Exception {

netty-socketio-core/src/main/java/com/socketio4j/socketio/listener/ClientListeners.java

@@ -25,13 +25,33 @@ public interface ClientListeners {
 
     void addEventInterceptor(EventInterceptor eventInterceptor);
 
-    void addDisconnectListener(DisconnectListener listener);
+    /**
+ * Registers a listener to be notified when the client disconnects.
+ *
+ * @param listener the disconnect listener to register
+ */
+void addDisconnectListener(DisconnectListener listener);
 
-    void removeDisconnectListener(DisconnectListener listener);
+    /**
+ * Removes a disconnect listener.
+ *
+ * @param listener the disconnect listener to remove
+ */
+void removeDisconnectListener(DisconnectListener listener);
 
-    void addConnectListener(ConnectListener listener);
+    /**
+ * Registers a listener to be notified when a client connects.
+ *
+ * @param listener the listener to register
+ */
+void addConnectListener(ConnectListener listener);
 
-    void removeConnectListener(ConnectListener listener);
+    /**
+ * Removes a listener that is notified when a client connects.
+ *
+ * @param listener the connect listener to remove
+ */
+void removeConnectListener(ConnectListener listener);
 
     /**
      * from v4, ping will always be sent by server except probe ping packet sent from client,

netty-socketio-core/src/main/java/com/socketio4j/socketio/namespace/Namespace.java

@@ -289,16 +289,31 @@ public void addConnectListener(ConnectListener listener) {
         connectListeners.add(listener);
     }
 
+    /**
+     * Removes a listener invoked when a client connects to the namespace.
+     *
+     * @param listener the connection listener to remove
+     */
     @Override
     public void removeConnectListener(ConnectListener listener) {
         connectListeners.remove(listener);
     }
 
+    /**
+     * Removes a disconnect listener from this namespace.
+     *
+     * @param listener the disconnect listener to remove
+     */
     @Override
     public void removeDisconnectListener(DisconnectListener listener) {
         disconnectListeners.remove(listener);
     }
 
+    /**
+     * Registers a client with the namespace and notifies the connection listeners.
+     *
+     * @param client the client connecting to the namespace
+     */
     public void onConnect(SocketIOClient client) {
         if (roomClients.containsKey(getName())
                 && roomClients.get(getName()).contains(client.getSessionId())) {
@@ -430,6 +445,12 @@ public void joinRooms(Set<String> rooms, final UUID sessionId) {
         storeFactory.eventStore().publish(EventType.BULK_JOIN, new BulkJoinMessage(sessionId, rooms, getName()));
     }
 
+    /**
+     * Sends a packet to every locally connected client in the specified room.
+     *
+     * @param room   the target room
+     * @param packet the packet to send
+     */
     public void dispatch(String room, Packet packet) {
         int size = forEachRoomClient(room, client -> {
             // Produce a per-client copy so that the shared Packet is never mutated.

netty-socketio-core/src/main/java/com/socketio4j/socketio/protocol/JacksonJsonSupport.java

@@ -76,6 +76,12 @@ protected AckArgsDeserializer() {
             super(AckArgs.class);
         }
 
+        /**
+         * Deserializes acknowledgment arguments according to the current callback's expected types.
+         *
+         * @param  jp the JSON parser containing the acknowledgment arguments
+         * @return     the deserialized acknowledgment arguments
+         */
         @Override
         public AckArgs deserialize(JsonParser jp, DeserializationContext ctxt) throws IOException {
             List<Object> args = new ArrayList<Object>();

netty-socketio-core/src/main/java/com/socketio4j/socketio/protocol/Packet.java

@@ -86,13 +86,13 @@ public <T> T getData() {
     }
 
     /**
-     * Creates a copy of #{@link Packet} with new namespace set
-     * if it differs from current namespace.
-     * Otherwise, returns original object unchanged
+     * Creates a packet with the specified namespace and Engine.IO version when the
+     * namespace differs from the current namespace.
      *
-     * @param namespace
-     * @param engineIOVersion
-     * @return packet
+     * @param namespace the namespace to set
+     * @param engineIOVersion the Engine.IO version to set on a copied packet
+     * @return the original packet when the namespace matches case-insensitively;
+     *         otherwise, a shallow copy with the specified namespace and version
      */
     public Packet withNsp(String namespace, EngineIOVersion engineIOVersion) {
         if (this.nsp.equalsIgnoreCase(namespace)) {
@@ -112,16 +112,10 @@ public Packet withNsp(String namespace, EngineIOVersion engineIOVersion) {
     }
 
     /**
-     * Returns a packet with the given {@link EngineIOVersion} stamped in.
-     * <p>
-     * If {@code engineIOVersion} is already equal to this packet's version, {@code this} is
-     * returned unchanged — no allocation. Otherwise a shallow copy is created so that the
-     * shared original is never mutated. This matters during room broadcasts: {@code ClientHead.send}
-     * only enqueues the packet; {@code EncoderHandler} reads the version later on a Netty
-     * event-loop thread, so every client must hold its own stable version reference.
+     * Creates a packet associated with the specified Engine.IO version.
      *
-     * @param engineIOVersion the EIO version to stamp onto the packet
-     * @return {@code this} if the version already matches, otherwise a new {@link Packet}
+     * @param engineIOVersion the Engine.IO version to associate with the packet
+     * @return this packet if the version matches; otherwise, a shallow copy with the specified version
      */
     public Packet withEngineIOVersion(EngineIOVersion engineIOVersion) {
         if (engineIOVersion == this.engineIOVersion) {
@@ -139,6 +133,11 @@ public Packet withEngineIOVersion(EngineIOVersion engineIOVersion) {
         return copy;
     }
 
+    /**
+     * Sets the packet namespace, converting the empty namespace object representation to an empty string.
+     *
+     * @param endpoint the namespace endpoint
+     */
     public void setNsp(String endpoint) {
         //patch for #903
         if ("{}".equals(endpoint)){