doc: added comments

Author: objz

api/src/main/java/dev/objz/commandbridge/api/CommandBridgeAPI.java

@@ -14,23 +14,61 @@
 import java.util.concurrent.CompletableFuture;
 import java.util.function.Consumer;
 
+/** Main entry point for interacting with the CommandBridge network. */
 public interface CommandBridgeAPI {
 
+    /**
+     * Obtains a {@link MessageChannel} for the given {@link ChannelType}.
+     *
+     * @param type the channel type identity
+     * @param <T> the payload type
+     * @param <C> the channel interface type
+     * @return the message channel
+     */
     <T extends ChannelPayload, C extends MessageChannel<T>> C channel(ChannelType<T, C> type);
 
+    /**
+     * Broadcasts a payload to all connected servers on a specific channel.
+     *
+     * @param channel the channel to broadcast on
+     * @param payload the data to send
+     * @return a future that completes when the broadcast is dispatched
+     */
     <P extends ChannelPayload> CompletableFuture<Void> broadcast(MessageChannel<P> channel, P payload);
 
+    /** @return the identity of the current server */
     Platform.ServerTarget server();
 
+    /** @return the current connection state to the bridge network */
     ConnectionState connectionState();
 
+    /** @return the IDs of all currently connected servers, if available */
     Optional<Set<String>> connectedServers();
 
+    /** @return the player location lookup service, if available */
     Optional<PlayerLocator> playerLocator();
 
+    /**
+     * Subscribes to server connection events.
+     *
+     * @param listener the listener to call when a server connects
+     * @return a subscription handle to cancel the listener
+     */
     Subscription onServerConnected(ServerEventListener listener);
 
+    /**
+     * Subscribes to server disconnection events.
+     *
+     * @param listener the listener to call when a server disconnects
+     * @return a subscription handle to cancel the listener
+     */
     Subscription onServerDisconnected(ServerEventListener listener);
 
+    /**
+     * Subscribes to connection state changes.
+     *
+     * @param listener the listener to call when the state changes
+     * @return a subscription handle to cancel the listener
+     */
     Subscription onConnectionStateChanged(Consumer<ConnectionState> listener);
 }

api/src/main/java/dev/objz/commandbridge/api/CommandBridgeProvider.java

@@ -2,6 +2,7 @@
 
 import java.util.Objects;
 
+/** Static provider for accessing the {@link CommandBridgeAPI} instance. */
 public final class CommandBridgeProvider {
 
     private static volatile CommandBridgeAPI instance;
@@ -10,13 +11,25 @@ private CommandBridgeProvider() {
         throw new UnsupportedOperationException("Provider can't be instanced");
     }
 
+    /**
+     * @return the registered API instance
+     * @throws IllegalStateException if the API is not registered
+     */
     public static CommandBridgeAPI get() {
         if (instance == null) {
             throw new IllegalStateException("CommandBridge is not available. Is it installed and running?");
         }
         return instance;
     }
 
+    /**
+     * Obtains the API instance cast to a specific type.
+     *
+     * @param type the API class type
+     * @param <T> the API type
+     * @return the cast API instance
+     * @throws IllegalStateException if the instance is not available or compatible
+     */
     public static <T extends CommandBridgeAPI> T get(Class<T> type) {
         CommandBridgeAPI api = get();
         if (!type.isInstance(api)) {
@@ -25,6 +38,12 @@ public static <T extends CommandBridgeAPI> T get(Class<T> type) {
         return type.cast(api);
     }
 
+    /**
+     * Registers the API implementation.
+     *
+     * @param impl the implementation to register
+     * @throws IllegalStateException if an implementation is already registered
+     */
     public static void register(CommandBridgeAPI impl) {
         Objects.requireNonNull(impl);
         if (instance != null) {
@@ -33,6 +52,7 @@ public static void register(CommandBridgeAPI impl) {
         instance = impl;
     }
 
+    /** Unregisters the current API implementation. */
     public static void unregister() {
         instance = null;
     }

api/src/main/java/dev/objz/commandbridge/api/channel/ChannelPayload.java

@@ -1,4 +1,5 @@
 package dev.objz.commandbridge.api.channel;
 
+/** Marker interface for data sent over a {@link MessageChannel}. */
 public interface ChannelPayload {
 }

api/src/main/java/dev/objz/commandbridge/api/channel/ChannelType.java

@@ -2,6 +2,12 @@
 
 import java.util.Objects;
 
+/**
+ * Identity and type information for a {@link MessageChannel}.
+ *
+ * @param <T> the payload type
+ * @param <C> the channel interface type
+ */
 public abstract class ChannelType<T extends ChannelPayload, C extends MessageChannel<T>> {
 
     private final Class<T> type;
@@ -10,6 +16,7 @@ protected ChannelType(Class<T> type) {
         this.type = Objects.requireNonNull(type);
     }
 
+    /** @return the class of the payload handled by this channel */
     public Class<T> type() {
         return type;
     }

api/src/main/java/dev/objz/commandbridge/api/channel/Channels.java

@@ -2,8 +2,10 @@
 
 import dev.objz.commandbridge.api.channel.command.CommandChannelType;
 
+/** Registry of built-in {@link ChannelType}s. */
 public final class Channels {
 
+    /** The default channel for executing commands. */
     public static final CommandChannelType COMMAND = new CommandChannelType();
 
     private Channels() {

api/src/main/java/dev/objz/commandbridge/api/channel/MessageChannel.java

@@ -7,13 +7,46 @@
 import java.time.Duration;
 import java.util.concurrent.CompletableFuture;
 
+/**
+ * Communication pipe for sending and receiving {@link ChannelPayload}s.
+ *
+ * @param <P> the type of payload handled by this channel
+ */
 public interface MessageChannel<P extends ChannelPayload> {
 
+    /**
+     * Sends a payload to a target server without expecting a response.
+     *
+     * @param target the destination server
+     * @param payload the data to send
+     * @return a future that completes when the message is sent
+     */
     CompletableFuture<Void> send(Platform.ServerTarget target, P payload);
 
+    /**
+     * Sends a request to a target server and waits for a response.
+     *
+     * @param target the destination server
+     * @param payload the request data
+     * @return a future containing the response payload
+     */
     CompletableFuture<P> request(Platform.ServerTarget target, P payload);
 
+    /**
+     * Sends a request to a target server with a custom timeout.
+     *
+     * @param target the destination server
+     * @param payload the request data
+     * @param timeout the maximum time to wait for a response
+     * @return a future containing the response payload
+     */
     CompletableFuture<P> request(Platform.ServerTarget target, P payload, Duration timeout);
 
+    /**
+     * Subscribes a listener to messages received on this channel.
+     *
+     * @param listener the listener to call for incoming messages
+     * @return a subscription handle to cancel the listener
+     */
     Subscription listen(MessageListener<P> listener);
 }

api/src/main/java/dev/objz/commandbridge/api/channel/command/CommandChannel.java

@@ -6,16 +6,40 @@
 import java.util.UUID;
 import java.util.concurrent.CompletableFuture;
 
+/** Specialized channel for dispatching commands to servers. */
 public interface CommandChannel extends MessageChannel<CommandPayload> {
 
+    /**
+     * Executes a command as the console.
+     *
+     * @param target the destination server
+     * @param command the command string to run
+     * @return a future that completes when the command is sent
+     */
     default CompletableFuture<Void> console(Platform.ServerTarget target, String command) {
         return send(target, CommandPayload.console(command));
     }
 
+    /**
+     * Executes a command as a specific player.
+     *
+     * @param target the destination server
+     * @param command the command string to run
+     * @param player the UUID of the player to run as
+     * @return a future that completes when the command is sent
+     */
     default CompletableFuture<Void> player(Platform.ServerTarget target, String command, UUID player) {
         return send(target, CommandPayload.player(command, player));
     }
 
+    /**
+     * Executes a command with operator permissions, bypassing standard checks.
+     *
+     * @param target the destination server
+     * @param command the command string to run
+     * @param player the UUID of the player to run as
+     * @return a future that completes when the command is sent
+     */
     default CompletableFuture<Void> operator(Platform.ServerTarget target, String command, UUID player) {
         return send(target, CommandPayload.operator(command, player));
     }

api/src/main/java/dev/objz/commandbridge/api/channel/command/CommandChannelType.java

@@ -2,8 +2,10 @@
 
 import dev.objz.commandbridge.api.channel.ChannelType;
 
+/** Identity for the {@link CommandChannel}. */
 public final class CommandChannelType extends ChannelType<CommandPayload, CommandChannel> {
 
+    /** Creates a new command channel type. */
     public CommandChannelType() {
         super(CommandPayload.class);
     }

api/src/main/java/dev/objz/commandbridge/api/channel/command/CommandPayload.java

@@ -4,16 +4,26 @@
 
 import java.util.UUID;
 
+/**
+ * Payload for command execution.
+ *
+ * @param command the command string to run
+ * @param runAs the execution mode
+ * @param player the optional player context
+ */
 public record CommandPayload(String command, RunAs runAs, UUID player) implements ChannelPayload {
 
+    /** Creates a payload for console execution. */
     public static CommandPayload console(String command) {
         return new CommandPayload(command, RunAs.CONSOLE, null);
     }
 
+    /** Creates a payload for player execution. */
     public static CommandPayload player(String command, UUID player) {
         return new CommandPayload(command, RunAs.PLAYER, player);
     }
 
+    /** Creates a payload for operator execution. */
     public static CommandPayload operator(String command, UUID player) {
         return new CommandPayload(command, RunAs.OPERATOR, player);
     }

api/src/main/java/dev/objz/commandbridge/api/channel/command/RunAs.java

@@ -1,7 +1,11 @@
 package dev.objz.commandbridge.api.channel.command;
 
+/** Defines the execution context for a command. */
 public enum RunAs {
+    /** Run as the server console. */
     CONSOLE,
+    /** Run as a specific player. */
     PLAYER,
+    /** Run as a player with temporary operator permissions. */
     OPERATOR
 }