docs(api): replace inline code-block labels with JDK-style prose lead-ins

Author: objz

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

@@ -22,26 +22,38 @@
  * {@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:
+ * <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:
  *
- * // Send a command to a backend
+ * <pre>{@code
  * channel.to(List.of(Platform.backend("survival-1")))
  *        .send(new CommandPayload("say hello", RunAs.CONSOLE));
+ * }</pre>
+ *
+ * <p>To broadcast a command to every connected server:
  *
- * // Broadcast to all connected servers
+ * <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):
  *
- * // Subscribe to server connection events (proxy only)
+ * <pre>{@code
  * api.onServerConnected(server ->
  *     System.out.println("Connected: " + server.id())
  * ).ifPresent(subscriptions::add);
+ * }</pre>
+ *
+ * <p>To track connection state transitions on any platform:
  *
- * // React to connection state changes (all platforms)
+ * <pre>{@code
  * api.onConnectionStateChanged(state -> {
  *     if (state.isActive()) {
  *         // ready to send

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

@@ -11,15 +11,14 @@
  *
  * <p>This class cannot be instantiated. All access is through static methods.
  *
+ * <p>To obtain the API instance:
+ *
  * <pre>{@code
- * // Basic usage — obtain the API
  * CommandBridgeAPI api = CommandBridgeProvider.get();
- *
- * // Platform-specific usage (Velocity proxy only):
- * // VelocityCommandBridgeAPI velocityApi =
- * //     CommandBridgeProvider.get(VelocityCommandBridgeAPI.class);
  * }</pre>
  *
+ * <p>To access a platform-specific subtype, pass the expected class to {@link #get(Class)}.
+ *
  * @see CommandBridgeAPI
  */
 public final class CommandBridgeProvider {

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

@@ -22,22 +22,27 @@
  * <p>All send operations return {@link java.util.concurrent.CompletableFuture} and are
  * non-blocking.
  *
+ * <p>To obtain a channel and send a command to a specific backend server:
+ *
  * <pre>{@code
  * CommandBridgeAPI api = CommandBridgeProvider.get();
  * MessageChannel<CommandPayload> channel = api.channel(CommandPayload.class);
- *
- * // Send a command to a specific backend
  * channel.to(List.of(Platform.backend("survival-1")))
  *        .send(new CommandPayload("say hello", RunAs.CONSOLE));
+ * }</pre>
+ *
+ * <p>To broadcast a command to every connected server:
  *
- * // Broadcast to all connected servers
+ * <pre>{@code
  * channel.toAll().send(new CommandPayload("say maintenance soon", RunAs.CONSOLE));
+ * }</pre>
  *
- * // Listen for incoming commands
- * Subscription sub = channel.listen((ctx, payload) -> {
- *     System.out.println("Command from " + ctx.from().id() + ": " + payload.command());
- * });
- * sub.cancel(); // when done
+ * <p>To receive incoming messages on this channel, register a listener and cancel it when done:
+ *
+ * <pre>{@code
+ * Subscription sub = channel.listen((ctx, payload) ->
+ *     System.out.println("Command from " + ctx.from().id() + ": " + payload.command()));
+ * sub.cancel();
  * }</pre>
  *
  * @param <P> the type of payload handled by this channel; must extend
@@ -114,6 +119,7 @@ interface Sender<P extends ChannelPayload> {
          * @return a {@link java.util.concurrent.CompletableFuture} that completes with the
          *         response payload, or completes exceptionally if the default timeout elapses
          *         before a response is received
+         * @throws UnsupportedOperationException if this sender targets more than one server
          * @see #request(ChannelPayload, java.time.Duration)
          */
         CompletableFuture<P> request(P payload);
@@ -129,6 +135,7 @@ interface Sender<P extends ChannelPayload> {
          * @param timeout the maximum duration to wait for a response; must not be {@code null}
          * @return a {@link java.util.concurrent.CompletableFuture} that completes with the
          *         response payload, or completes exceptionally if the timeout elapses
+         * @throws UnsupportedOperationException if this sender targets more than one server
          * @see #request(ChannelPayload)
          */
         CompletableFuture<P> request(P payload, Duration timeout);

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

@@ -16,18 +16,24 @@
  * {@link dev.objz.commandbridge.api.channel.MessageChannel} obtained from
  * {@link dev.objz.commandbridge.api.CommandBridgeAPI#channel(Class)}.
  *
+ * <p>To run a command as the server console on a specific backend server:
+ *
  * <pre>{@code
  * MessageChannel<CommandPayload> channel = api.channel(CommandPayload.class);
- *
- * // Execute a command as console
  * channel.to(List.of(Platform.backend("survival-1")))
  *        .send(new CommandPayload("say hello", RunAs.CONSOLE));
+ * }</pre>
+ *
+ * <p>To run a command as a specific online player with their normal permissions:
  *
- * // Execute as a specific player
+ * <pre>{@code
  * channel.to(List.of(Platform.backend("survival-1")))
  *        .send(new CommandPayload("home", RunAs.PLAYER, playerUUID));
+ * }</pre>
  *
- * // Execute as a player with temporary operator permissions
+ * <p>To run a command as a player with temporary operator-level permissions:
+ *
+ * <pre>{@code
  * channel.to(List.of(Platform.backend("survival-1")))
  *        .send(new CommandPayload("gamemode creative", RunAs.OPERATOR, playerUUID));
  * }</pre>

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

@@ -8,15 +8,21 @@
  * commands, user-context commands with normal permissions, and elevated commands that
  * temporarily grant operator status to a specific player.
  *
- * <p>Usage examples:
+ * <p>To run a command as the server console, with full permissions and no player context:
+ *
  * <pre>{@code
- * // Run a command as console
  * new CommandPayload("say hello", RunAs.CONSOLE)
+ * }</pre>
  *
- * // Run a command as a specific player
+ * <p>To run a command as a specific online player, with their normal permissions:
+ *
+ * <pre>{@code
  * new CommandPayload("home", RunAs.PLAYER, playerUUID)
+ * }</pre>
+ *
+ * <p>To run a command as a player with temporary operator-level permissions:
  *
- * // Run a command as a player with operator permissions
+ * <pre>{@code
  * new CommandPayload("gamemode creative", RunAs.OPERATOR, playerUUID)
  * }</pre>
  *

api/src/main/java/dev/objz/commandbridge/api/message/MessageListener.java

@@ -12,16 +12,20 @@
  * which returns a {@link dev.objz.commandbridge.api.message.Subscription} that can be
  * used to cancel the listener.
  *
+ * <p>To register a listener as a lambda and retain the returned {@link Subscription}:
+ *
  * <pre>{@code
  * MessageChannel<CommandPayload> channel = api.channel(CommandPayload.class);
  *
  * Subscription sub = channel.listen((ctx, payload) -> {
  *     String from = ctx.from().id();
  *     String command = payload.command();
- *     // handle the incoming command
  * });
+ * }</pre>
  *
- * // To stop receiving messages:
+ * <p>Pass the subscription to {@link Subscription#cancel()} to stop receiving messages:
+ *
+ * <pre>{@code
  * sub.cancel();
  * }</pre>
  *

api/src/main/java/dev/objz/commandbridge/api/message/Subscription.java

@@ -11,17 +11,22 @@
  *
  * <p>Calling {@link #cancel()} is idempotent: invoking it more than once has no effect.
  *
+ * <p>To register a listener on a channel and retain the subscription:
+ *
  * <pre>{@code
- * // Register a listener and store the subscription
  * Subscription sub = api.channel(CommandPayload.class)
  *     .listen((ctx, payload) -> handleCommand(ctx, payload));
+ * }</pre>
  *
- * // Later, during shutdown:
+ * <p>To cancel the listener, for example during plugin shutdown:
+ *
+ * <pre>{@code
  * sub.cancel();
  * }</pre>
  *
  * @see dev.objz.commandbridge.api.channel.MessageChannel#listen(dev.objz.commandbridge.api.message.MessageListener)
  * @see dev.objz.commandbridge.api.CommandBridgeAPI#onServerConnected(dev.objz.commandbridge.api.message.ServerEventListener)
+ * @see dev.objz.commandbridge.api.message.MessageListener
  */
 @FunctionalInterface
 public interface Subscription {

api/src/main/java/dev/objz/commandbridge/api/platform/ConnectionState.java

@@ -13,6 +13,7 @@
  * {@code AUTH_FAILED} and no further connection attempts are made.
  *
  * @see #isActive()
+ * @see dev.objz.commandbridge.api.CommandBridgeAPI#connectionState()
  */
 public enum ConnectionState {
 

api/src/main/java/dev/objz/commandbridge/api/platform/PlayerLocator.java

@@ -23,6 +23,7 @@
  * }</pre>
  *
  * @see dev.objz.commandbridge.api.CommandBridgeAPI#playerLocator()
+ * @see dev.objz.commandbridge.api.platform.Platform.ServerTarget
  */
 @FunctionalInterface
 public interface PlayerLocator {