Add comprehensive Javadoc documentation to server components, including annotations, request/response handling, routing, and WebSocket support.

src/main/java/dev/coph/nextusweb/server/websocket/WebSocketGroup.java

@@ -8,43 +8,93 @@ import io.netty.handler.codec.http.websocketx.TextWebSocketFrame;
 import io.netty.util.concurrent.GlobalEventExecutor;
 import tools.jackson.core.JacksonException;
 
+/**
+ * A named collection of WebSocket connections that supports broadcasting to all members at
+ * once — useful for chat rooms, pub/sub topics, presence channels and similar fan-out
+ * scenarios.
+ *
+ * <p>It is backed by a Netty {@link ChannelGroup}, which automatically removes channels as they
+ * close, so callers do not need to prune disconnected sessions manually. The group is
+ * thread-safe.</p>
+ */
 public final class WebSocketGroup {
 
+    /** Underlying Netty channel group holding the member connections. */
     private final ChannelGroup channels;
+    /** Human-readable name of this group. */
     private final String name;
 
+    /**
+     * Creates an unnamed group (named {@code "anonymous"}).
+     */
     public WebSocketGroup() {
         this("anonymous");
     }
 
+    /**
+     * Creates a named group.
+     *
+     * @param name the group name
+     */
     public WebSocketGroup(String name) {
         this.name = name;
         this.channels = new DefaultChannelGroup(name, GlobalEventExecutor.INSTANCE);
     }
 
+    /**
+     * @return the group name
+     */
     public String name() {
         return name;
     }
 
+    /**
+     * Adds a session to the group.
+     *
+     * @param session the session to add
+     * @return this group, for fluent chaining
+     */
     public WebSocketGroup add(WebSocketSession session) {
         channels.add(session.channel());
         return this;
     }
 
+    /**
+     * Removes a session from the group.
+     *
+     * @param session the session to remove
+     * @return this group, for fluent chaining
+     */
     public WebSocketGroup remove(WebSocketSession session) {
         channels.remove(session.channel());
         return this;
     }
 
+    /**
+     * @return the current number of member connections
+     */
     public int size() {
         return channels.size();
     }
 
+    /**
+     * Broadcasts a text message to every member of the group.
+     *
+     * @param text the text to send
+     * @return this group, for fluent chaining
+     */
     public WebSocketGroup broadcast(String text) {
         channels.writeAndFlush(new TextWebSocketFrame(text));
         return this;
     }
 
+    /**
+     * Serializes the given value to JSON and broadcasts it as a text message to every member.
+     *
+     * @param value the object to serialize and broadcast
+     * @return this group, for fluent chaining
+     * @throws RuntimeException if JSON serialization fails
+     */
     public WebSocketGroup broadcastJson(Object value) {
         try {
             byte[] bytes = JsonMapper.MAPPER.writeValueAsBytes(value);
@@ -56,6 +106,12 @@ public final class WebSocketGroup {
         return this;
     }
 
+    /**
+     * Broadcasts a binary message to every active member, allocating a fresh buffer per channel.
+     *
+     * @param data the bytes to broadcast
+     * @return this group, for fluent chaining
+     */
     public WebSocketGroup broadcastBinary(byte[] data) {
         for (var ch : channels) {
             if (ch.isActive()) {
@@ -66,6 +122,14 @@ public final class WebSocketGroup {
         return this;
     }
 
+    /**
+     * Broadcasts a text message to every active member except one &mdash; typically the sender,
+     * so a client does not receive its own message echoed back.
+     *
+     * @param exclude the session to skip, or {@code null} to broadcast to everyone
+     * @param text    the text to send
+     * @return this group, for fluent chaining
+     */
     public WebSocketGroup broadcastExcept(WebSocketSession exclude, String text) {
         var excludeCh = exclude == null ? null : exclude.channel();
         for (var ch : channels) {
@@ -76,6 +140,11 @@ public final class WebSocketGroup {
         return this;
     }
 
+    /**
+     * Closes every connection in the group.
+     *
+     * @return this group, for fluent chaining
+     */
     public WebSocketGroup closeAll() {
         channels.close();
         return this;