docs(api): apply formatting cleanup across all API JavaDocs

Author: objz

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

@@ -13,45 +13,55 @@
 import java.util.function.Consumer;
 
 /**
- * Primary interface for interacting with the CommandBridge network from a third-party plugin.
+ * Primary interface for interacting with the CommandBridge network from a
+ * third-party plugin.
  *
- * <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
+ * <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;
+ * {@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()} and use {@link #channel(Class)}
+ * <p>
+ * Obtain an instance via {@link CommandBridgeProvider#get()} and use
+ * {@link #channel(Class)}
  * to build a typed message channel:
  *
  * <pre>{@code
  * CommandBridgeAPI api = CommandBridgeProvider.get();
  * MessageChannel<CommandPayload> channel = api.channel(CommandPayload.class);
  * }</pre>
  *
- * <p>To send a command to a specific backend server:
+ * <p>
+ * To send a command to a specific backend server:
  *
  * <pre>{@code
  * channel.to(List.of(Platform.backend("survival-1")))
- *        .send(new CommandPayload("say hello", RunAs.CONSOLE));
+ *         .send(new CommandPayload("say hello", RunAs.CONSOLE));
  * }</pre>
  *
- * <p>To broadcast a command to every connected server:
+ * <p>
+ * To broadcast a command to every connected server:
  *
  * <pre>{@code
  * channel.toAll().send(new CommandPayload("say maintenance soon", RunAs.CONSOLE));
  * }</pre>
  *
- * <p>To receive a notification when a backend server connects (Velocity proxy only):
+ * <p>
+ * To receive a notification when a backend server connects (Velocity proxy
+ * only):
  *
  * <pre>{@code
- * api.onServerConnected(server ->
- *     System.out.println("Connected: " + server.id())
- * ).ifPresent(subscriptions::add);
+ * api.onServerConnected(server -> System.out.println("Connected: " + server.id())).ifPresent(subscriptions::add);
  * }</pre>
  *
- * <p>To track connection state transitions on any platform:
+ * <p>
+ * To track connection state transitions on any platform:
  *
  * <pre>{@code
  * api.onConnectionStateChanged(state -> {
@@ -67,66 +77,85 @@
 public interface CommandBridgeAPI {
 
     /**
-     * Obtains a typed {@link dev.objz.commandbridge.api.channel.MessageChannel} for the given
+     * Obtains a typed {@link dev.objz.commandbridge.api.channel.MessageChannel} for
+     * the given
      * payload type.
      *
-     * @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}
+     * @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);
 
     /**
      * 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
+     * @return the {@link dev.objz.commandbridge.api.platform.Platform.ServerTarget}
+     *         of the current
+     *         server, containing its configured identifier and platform type
      */
     Platform.ServerTarget server();
 
     /**
-     * Returns the current connection state of this server to the CommandBridge network.
+     * Returns the current connection state of this server to the CommandBridge
+     * network.
      *
      * @return the current {@link ConnectionState}
      * @see ConnectionState#isActive()
      */
     ConnectionState connectionState();
 
     /**
-     * Returns the identifiers of all servers currently connected to the bridge network.
+     * 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
+     * <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
+     * @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();
 
     /**
-     * Returns the player location service for resolving which server a player is connected to.
+     * 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
+     * <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
+     * @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>This method is available only on the Velocity proxy. On backend servers, it returns
+     * <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 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
+     * @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()
      */
@@ -135,13 +164,17 @@ public interface CommandBridgeAPI {
     /**
      * Subscribes to server disconnection events.
      *
-     * <p>This method is available only on the Velocity proxy. On backend servers, it returns
+     * <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 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
+     * @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()
      */
@@ -150,12 +183,16 @@ public interface CommandBridgeAPI {
     /**
      * Subscribes to connection state changes on this server.
      *
-     * <p>Available on all platforms, unlike the server event methods. The listener is invoked on
+     * <p>
+     * Available on all platforms, unlike the server event methods. The listener is
+     * invoked on
      * every state transition.
      *
-     * @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
+     * @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

@@ -3,21 +3,30 @@
 import java.util.Objects;
 
 /**
- * Static provider for obtaining the {@link CommandBridgeAPI} singleton 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>
+ * 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.
+ * <p>
+ * This class cannot be instantiated. All access is through static methods.
  *
- * <p>To obtain the API instance:
+ * <p>
+ * To obtain the API instance:
  *
  * <pre>{@code
  * CommandBridgeAPI api = CommandBridgeProvider.get();
  * }</pre>
  *
- * <p>To access a platform-specific subtype, pass the expected class to {@link #get(Class)}.
+ * <p>
+ * To access a platform-specific subtype, pass the expected class to
+ * {@link #get(Class)}.
  *
  * @see CommandBridgeAPI
  */
@@ -32,11 +41,13 @@ private CommandBridgeProvider() {
     /**
      * Returns the registered {@link CommandBridgeAPI} instance.
      *
-     * <p>This method is safe to call from any thread after CommandBridge has enabled.
+     * <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
+     * @throws IllegalStateException if CommandBridge is not installed, not yet
+     *                               enabled,
+     *                               or the API has not been registered
      * @see #get(Class)
      */
     public static CommandBridgeAPI get() {
@@ -47,17 +58,23 @@ public static CommandBridgeAPI get() {
     }
 
     /**
-     * Returns the registered {@link CommandBridgeAPI} instance cast to the specified subtype.
+     * Returns the registered {@link CommandBridgeAPI} instance cast to the
+     * specified subtype.
      *
-     * <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,
+     * <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}
+     * @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}
+     * @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) {
@@ -71,12 +88,14 @@ public static <T extends CommandBridgeAPI> T get(Class<T> type) {
     /**
      * Registers the {@link CommandBridgeAPI} implementation.
      *
-     * <p>This method is called internally by the CommandBridge plugin during startup and is not
+     * <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; must not be {@code null}
      * @throws IllegalStateException if an implementation is already registered
-     * @throws NullPointerException if {@code impl} is {@code null}
+     * @throws NullPointerException  if {@code impl} is {@code null}
      */
     public static synchronized void register(CommandBridgeAPI impl) {
         Objects.requireNonNull(impl);
@@ -89,8 +108,11 @@ public static synchronized void register(CommandBridgeAPI impl) {
     /**
      * 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
+     * <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() {

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

@@ -4,18 +4,26 @@
  * 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}
+ * <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
+ * <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:
+ * <p>
+ * Example of a custom payload type:
+ * 
  * <pre>{@code
- * public record MyPayload(String data) implements ChannelPayload {}
+ * public record MyPayload(String data) implements ChannelPayload {
+ * }
  *
  * MessageChannel<MyPayload> channel = api.channel(MyPayload.class);
  * channel.toAll().send(new MyPayload("hello"));