docs(api): rewrite JavaDocs to JDK-standard quality across entire API module

Author: objz

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

@@ -13,65 +13,138 @@
 import java.util.function.Consumer;
 
 /**
- * Main entry point for interacting with the CommandBridge network.
+ * Primary interface for interacting with the CommandBridge network from a third-party plugin.
  *
- * <p>Methods returning {@link java.util.Optional} indicate proxy-only features;
- * they return {@code Optional.empty()} on backend servers and a present value on the Velocity proxy.
+ * <p>Use {@link #channel(Class)} to obtain typed message channels for sending and receiving
+ * payloads. {@link #server()} and {@link #connectionState()} expose the current server's identity
+ * and connection status. {@link #connectedServers()}, {@link #playerLocator()},
+ * {@link #onServerConnected(ServerEventListener)}, and
+ * {@link #onServerDisconnected(ServerEventListener)} are available only on the Velocity proxy;
+ * they return {@code Optional.empty()} on backend servers.
+ *
+ * <p>Obtain an instance via {@link CommandBridgeProvider#get()}. The following example shows
+ * common usage patterns:
+ *
+ * <pre>{@code
+ * CommandBridgeAPI api = CommandBridgeProvider.get();
+ * MessageChannel<CommandPayload> channel = api.channel(CommandPayload.class);
+ *
+ * // Send a command to a backend
+ * channel.to(List.of(Platform.backend("survival-1")))
+ *        .send(new CommandPayload("say hello", RunAs.CONSOLE));
+ *
+ * // Broadcast to all connected servers
+ * channel.toAll().send(new CommandPayload("say maintenance soon", RunAs.CONSOLE));
+ *
+ * // Subscribe to server connection events (proxy only)
+ * api.onServerConnected(server ->
+ *     System.out.println("Connected: " + server.id())
+ * ).ifPresent(subscriptions::add);
+ *
+ * // React to connection state changes (all platforms)
+ * api.onConnectionStateChanged(state -> {
+ *     if (state.isActive()) {
+ *         // ready to send
+ *     }
+ * });
+ * }</pre>
+ *
+ * @see CommandBridgeProvider
+ * @see dev.objz.commandbridge.api.channel.MessageChannel
  */
 public interface CommandBridgeAPI {
 
     /**
-     * Obtains a {@link MessageChannel} for the given payload type.
+     * Obtains a typed {@link dev.objz.commandbridge.api.channel.MessageChannel} for the given
+     * payload type.
      *
-     * @param type the payload class that identifies the channel
-     * @param <T> the payload type
-     * @return the message channel
+     * @param <T> the payload type; must extend {@link dev.objz.commandbridge.api.channel.ChannelPayload}
+     * @param type the {@link Class} token identifying the payload type; used for channel routing
+     * @return the message channel for sending and receiving payloads of type {@code T}
+     * @see dev.objz.commandbridge.api.channel.MessageChannel
      */
     <T extends ChannelPayload> MessageChannel<T> channel(Class<T> type);
 
-    /** @return the identity of the current server */
+    /**
+     * Returns the identity of the server this API instance is running on.
+     *
+     * @return the {@link dev.objz.commandbridge.api.platform.Platform.ServerTarget} of the current
+     *     server, containing its configured identifier and platform type
+     */
     Platform.ServerTarget server();
 
-    /** @return the current connection state to the bridge network */
+    /**
+     * Returns the current connection state of this server to the CommandBridge network.
+     *
+     * @return the current {@link ConnectionState}
+     * @see ConnectionState#isActive()
+     */
     ConnectionState connectionState();
 
-    /** @return the IDs of all currently connected servers, or empty if not available on this platform */
+    /**
+     * Returns the identifiers of all servers currently connected to the bridge network.
+     *
+     * <p>This method is available only on the Velocity proxy. On backend servers, it returns
+     * {@code Optional.empty()}.
+     *
+     * @return an {@link java.util.Optional} containing a snapshot of the connected server IDs if
+     *     called on the Velocity proxy, or an empty {@code Optional} on backend servers
+     * @see #onServerConnected(ServerEventListener)
+     */
     Optional<Set<String>> connectedServers();
 
-    /** @return the player location lookup service, or empty if not available on this platform */
+    /**
+     * Returns the player location service for resolving which server a player is connected to.
+     *
+     * <p>This method is available only on the Velocity proxy. On backend servers, it returns
+     * {@code Optional.empty()}.
+     *
+     * @return an {@link java.util.Optional} containing the {@link PlayerLocator} if called on the
+     *     Velocity proxy, or an empty {@code Optional} on backend servers
+     * @see dev.objz.commandbridge.api.platform.PlayerLocator#locate(java.util.UUID)
+     */
     Optional<PlayerLocator> playerLocator();
 
     /**
      * Subscribes to server connection events.
      *
-     * <p>Returns {@code Optional.empty()} on platforms where server connection events are not
-     * available (e.g. backend servers). On the Velocity proxy, returns a present {@link Optional}
-     * containing a {@link Subscription} that can be cancelled via {@link Subscription#cancel()}.
-     * Use {@link java.util.Optional#ifPresent(java.util.function.Consumer)} to handle safely.
+     * <p>This method is available only on the Velocity proxy. On backend servers, it returns
+     * {@code Optional.empty()} and the listener is not registered.
      *
-     * @param listener the listener to call when a server connects
-     * @return a present subscription handle on the proxy, or empty on backends
+     * @param listener the listener to invoke when a backend server connects to the bridge network;
+     *     must not be {@code null}
+     * @return an {@link java.util.Optional} containing the {@link Subscription} on the proxy, or
+     *     an empty {@code Optional} on backends
+     * @see #onServerDisconnected(ServerEventListener)
+     * @see dev.objz.commandbridge.api.message.Subscription#cancel()
      */
     Optional<Subscription> onServerConnected(ServerEventListener listener);
 
     /**
      * Subscribes to server disconnection events.
      *
-     * <p>Returns {@code Optional.empty()} on platforms where server disconnection events are not
-     * available (e.g. backend servers). On the Velocity proxy, returns a present {@link Optional}
-     * containing a {@link Subscription} that can be cancelled via {@link Subscription#cancel()}.
-     * Use {@link java.util.Optional#ifPresent(java.util.function.Consumer)} to handle safely.
+     * <p>This method is available only on the Velocity proxy. On backend servers, it returns
+     * {@code Optional.empty()} and the listener is not registered.
      *
-     * @param listener the listener to call when a server disconnects
-     * @return a present subscription handle on the proxy, or empty on backends
+     * @param listener the listener to invoke when a backend server disconnects from the bridge
+     *     network; must not be {@code null}
+     * @return an {@link java.util.Optional} containing the {@link Subscription} on the proxy, or
+     *     an empty {@code Optional} on backends
+     * @see #onServerConnected(ServerEventListener)
+     * @see dev.objz.commandbridge.api.message.Subscription#cancel()
      */
     Optional<Subscription> onServerDisconnected(ServerEventListener listener);
 
     /**
-     * Subscribes to connection state changes.
+     * Subscribes to connection state changes on this server.
+     *
+     * <p>Available on all platforms, unlike the server event methods. The listener is invoked on
+     * every state transition.
      *
-     * @param listener the listener to call when the state changes
-     * @return a subscription handle to cancel the listener
+     * @param listener the consumer to call with the new {@link ConnectionState} on each transition;
+     *     must not be {@code null}
+     * @return a {@link Subscription} that can be cancelled to stop receiving state change events
+     * @see ConnectionState
      */
     Subscription onConnectionStateChanged(Consumer<ConnectionState> listener);
 }

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

@@ -2,7 +2,26 @@
 
 import java.util.Objects;
 
-/** Static provider for accessing the {@link CommandBridgeAPI} instance. */
+/**
+ * Static provider for obtaining the {@link CommandBridgeAPI} singleton instance.
+ *
+ * <p>CommandBridge registers its implementation when the plugin enables. Third-party plugins
+ * retrieve the instance by calling {@link #get()} or {@link #get(Class)} for platform-specific
+ * subtypes. The provider holds a single volatile reference accessible across threads.
+ *
+ * <p>This class cannot be instantiated. All access is through static methods.
+ *
+ * <pre>{@code
+ * // Basic usage — obtain the API
+ * CommandBridgeAPI api = CommandBridgeProvider.get();
+ *
+ * // Platform-specific usage (Velocity proxy only):
+ * // VelocityCommandBridgeAPI velocityApi =
+ * //     CommandBridgeProvider.get(VelocityCommandBridgeAPI.class);
+ * }</pre>
+ *
+ * @see CommandBridgeAPI
+ */
 public final class CommandBridgeProvider {
 
     private static volatile CommandBridgeAPI instance;
@@ -12,8 +31,14 @@ private CommandBridgeProvider() {
     }
 
     /**
-     * @return the registered API instance
-     * @throws IllegalStateException if the API is not registered
+     * Returns the registered {@link CommandBridgeAPI} instance.
+     *
+     * <p>This method is safe to call from any thread after CommandBridge has enabled.
+     *
+     * @return the registered {@code CommandBridgeAPI} instance; never {@code null}
+     * @throws IllegalStateException if CommandBridge is not installed, not yet enabled,
+     *     or the API has not been registered
+     * @see #get(Class)
      */
     public static CommandBridgeAPI get() {
         if (instance == null) {
@@ -23,12 +48,18 @@ public static CommandBridgeAPI get() {
     }
 
     /**
-     * Obtains the API instance cast to a specific type.
+     * Returns the registered {@link CommandBridgeAPI} instance cast to the specified subtype.
      *
-     * @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
+     * <p>Use this method when accessing a platform-specific extension of the API. The cast is
+     * validated at runtime; if the registered instance does not implement the requested type,
+     * an {@link IllegalStateException} is thrown.
+     *
+     * @param <T> the expected API subtype; must extend {@link CommandBridgeAPI}
+     * @param type the {@link Class} token of the expected subtype; must not be {@code null}
+     * @return the API instance cast to {@code T}; never {@code null}
+     * @throws IllegalStateException if the API is not registered, or if the registered instance
+     *     is not an instance of {@code type}
+     * @see #get()
      */
     public static <T extends CommandBridgeAPI> T get(Class<T> type) {
         CommandBridgeAPI api = get();
@@ -39,10 +70,14 @@ public static <T extends CommandBridgeAPI> T get(Class<T> type) {
     }
 
     /**
-     * Registers the API implementation.
+     * Registers the {@link CommandBridgeAPI} implementation.
+     *
+     * <p>This method is called internally by the CommandBridge plugin during startup and is not
+     * intended for use by third-party plugins.
      *
-     * @param impl the implementation to register
+     * @param impl the implementation to register; must not be {@code null}
      * @throws IllegalStateException if an implementation is already registered
+     * @throws NullPointerException if {@code impl} is {@code null}
      */
     public static synchronized void register(CommandBridgeAPI impl) {
         Objects.requireNonNull(impl);
@@ -52,7 +87,13 @@ public static synchronized void register(CommandBridgeAPI impl) {
         instance = impl;
     }
 
-    /** Unregisters the current API implementation. */
+    /**
+     * Clears the registered {@link CommandBridgeAPI} implementation.
+     *
+     * <p>Called internally by the CommandBridge plugin during shutdown. After this method returns,
+     * calls to {@link #get()} will throw {@link IllegalStateException} until a new implementation
+     * is registered.
+     */
     public static synchronized void unregister() {
         instance = null;
     }

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

@@ -1,5 +1,28 @@
 package dev.objz.commandbridge.api.channel;
 
-/** Marker interface for data sent over a {@link MessageChannel}. */
+/**
+ * Marker interface for all data types that can be sent over a
+ * {@link dev.objz.commandbridge.api.channel.MessageChannel}.
+ *
+ * <p>Implementing this interface registers a type as a valid payload. The
+ * {@link dev.objz.commandbridge.api.channel.MessageChannel} uses the payload's {@code Class}
+ * token for channel routing and type-safe dispatch.
+ *
+ * <p>{@link dev.objz.commandbridge.api.channel.command.CommandPayload} is the built-in
+ * implementation for command execution. Custom payload types can be created by implementing
+ * this interface and using them with
+ * {@link dev.objz.commandbridge.api.CommandBridgeAPI#channel(Class)}.
+ *
+ * <p>Example of a custom payload type:
+ * <pre>{@code
+ * public record MyPayload(String data) implements ChannelPayload {}
+ *
+ * MessageChannel<MyPayload> channel = api.channel(MyPayload.class);
+ * channel.toAll().send(new MyPayload("hello"));
+ * }</pre>
+ *
+ * @see dev.objz.commandbridge.api.channel.command.CommandPayload
+ * @see dev.objz.commandbridge.api.channel.MessageChannel
+ */
 public interface ChannelPayload {
 }