docs(api): scope each type's JavaDoc examples to its own responsibility

Author: objz

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

@@ -17,59 +17,17 @@
  * 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
- * 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.
+ * Obtain an instance via {@link CommandBridgeProvider#get()}.
+ * Use {@link #channel(Class)} to obtain typed message channels,
+ * {@link #server()} and {@link #connectionState()} to query the current
+ * server's identity and connection status, and
+ * {@link #onServerConnected(ServerEventListener)} or
+ * {@link #onServerDisconnected(ServerEventListener)} to subscribe to
+ * server lifecycle events on the Velocity proxy.
  *
  * <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:
- *
- * <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:
- *
- * <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):
- *
- * <pre>{@code
- * api.onServerConnected(server -> System.out.println("Connected: " + server.id())).ifPresent(subscriptions::add);
- * }</pre>
- *
- * <p>
- * To track connection state transitions on any platform:
- *
- * <pre>{@code
- * api.onConnectionStateChanged(state -> {
- *     if (state.isActive()) {
- *         // ready to send
- *     }
- * });
- * }</pre>
+ * Methods returning {@link java.util.Optional} are available only on the
+ * Velocity proxy and return {@code Optional.empty()} on backend servers.
  *
  * @see CommandBridgeProvider
  * @see dev.objz.commandbridge.api.channel.MessageChannel

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

@@ -7,26 +7,16 @@
  * <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.
+ * {@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)}.
+ * built-in implementation for command execution. Custom payload types can be
+ * created by implementing this interface:
  *
- * <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

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

@@ -15,43 +15,36 @@
  *
  * <p>
  * A {@code MessageChannel} is bound to a specific payload type {@code P},
- * providing type-safe
- * message routing. Obtain an instance via
- * {@link dev.objz.commandbridge.api.CommandBridgeAPI#channel(Class)}.
- * Target one or more servers with {@link #to(java.util.Collection)} or
- * broadcast to all connected
- * servers with {@link #toAll()}. Subscribe to incoming messages with
+ * providing type-safe message routing. Target one or more servers with
+ * {@link #to(java.util.Collection)}, broadcast to all connected servers with
+ * {@link #toAll()}, or subscribe to incoming messages with
  * {@link #listen(dev.objz.commandbridge.api.message.MessageListener)}.
  *
  * <p>
- * All send operations return {@link java.util.concurrent.CompletableFuture} and
- * are
- * non-blocking.
+ * 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:
+ * To send a payload to a specific server:
  *
  * <pre>{@code
- * CommandBridgeAPI api = CommandBridgeProvider.get();
- * MessageChannel<CommandPayload> channel = api.channel(CommandPayload.class);
  * channel.to(List.of(Platform.backend("survival-1")))
- *         .send(new CommandPayload("say hello", RunAs.CONSOLE));
+ *         .send(payload);
  * }</pre>
  *
  * <p>
- * To broadcast a command to every connected server:
+ * To broadcast to every connected server:
  *
  * <pre>{@code
- * channel.toAll().send(new CommandPayload("say maintenance soon", RunAs.CONSOLE));
+ * channel.toAll().send(payload);
  * }</pre>
  *
  * <p>
- * To receive incoming messages on this channel, register a listener and cancel
- * it when done:
+ * To subscribe to incoming messages and cancel the listener later:
  *
  * <pre>{@code
- * Subscription sub = channel
- *         .listen((ctx, payload) -> System.out.println("Command from " + ctx.from().id() + ": " + payload.command()));
+ * Subscription sub = channel.listen((ctx, payload) ->
+ *         System.out.println("From " + ctx.from().id()));
  * sub.cancel();
  * }</pre>
  *

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

@@ -10,42 +10,35 @@
  *
  * <p>
  * The three components define what to run and how. {@code command} is the
- * command string
- * without a leading slash. {@code runAs} defines the execution context; see
- * {@link RunAs} for
- * available modes. {@code player} is the optional player UUID required when
- * {@code runAs} is
- * {@link RunAs#PLAYER} or {@link RunAs#OPERATOR}; pass {@code null} for
- * {@link RunAs#CONSOLE}.
+ * command string without a leading slash. {@code runAs} defines the execution
+ * context; see {@link RunAs} for available modes. {@code player} is the
+ * optional player UUID required when {@code runAs} is {@link RunAs#PLAYER}
+ * or {@link RunAs#OPERATOR}; pass {@code null} for {@link RunAs#CONSOLE}.
  *
  * <p>
  * Instances are sent through a
  * {@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:
+ * To create a console command with no player context:
  *
  * <pre>{@code
- * MessageChannel<CommandPayload> channel = api.channel(CommandPayload.class);
- * channel.to(List.of(Platform.backend("survival-1")))
- *         .send(new CommandPayload("say hello", RunAs.CONSOLE));
+ * new CommandPayload("say hello", RunAs.CONSOLE)
  * }</pre>
  *
  * <p>
- * To run a command as a specific online player with their normal permissions:
+ * To create a command that runs as a specific player:
  *
  * <pre>{@code
- * channel.to(List.of(Platform.backend("survival-1")))
- *         .send(new CommandPayload("home", RunAs.PLAYER, playerUUID));
+ * new CommandPayload("home", RunAs.PLAYER, playerUUID)
  * }</pre>
  *
  * <p>
- * To run a command as a player with temporary operator-level permissions:
+ * To create a command with temporary operator permissions:
  *
  * <pre>{@code
- * channel.to(List.of(Platform.backend("survival-1")))
- *         .send(new CommandPayload("gamemode creative", RunAs.OPERATOR, playerUUID));
+ * new CommandPayload("gamemode creative", RunAs.OPERATOR, playerUUID)
  * }</pre>
  *
  * @param command the command string to execute on the target server; must not

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

@@ -8,32 +8,19 @@
  *
  * <p>
  * This is a {@code @FunctionalInterface} and may be used as a lambda
- * expression.
- * Register an instance via
+ * expression. Register an instance via
  * {@link dev.objz.commandbridge.api.channel.MessageChannel#listen(MessageListener)},
  * which returns a {@link dev.objz.commandbridge.api.message.Subscription} that
- * can be
- * used to cancel the listener.
+ * can be used to cancel the listener.
  *
  * <p>
- * To register a listener as a lambda and retain the returned
- * {@link Subscription}:
+ * The listener receives the message metadata and the deserialized payload:
  *
  * <pre>{@code
- * MessageChannel<CommandPayload> channel = api.channel(CommandPayload.class);
- *
- * Subscription sub = channel.listen((ctx, payload) -> {
+ * (ctx, payload) -> {
  *     String from = ctx.from().id();
- *     String command = payload.command();
- * });
- * }</pre>
- *
- * <p>
- * Pass the subscription to {@link Subscription#cancel()} to stop receiving
- * messages:
- *
- * <pre>{@code
- * sub.cancel();
+ *     long sentAt = ctx.timestamp();
+ * }
  * }</pre>
  *
  * @param <T> the type of payload this listener handles;

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

@@ -8,17 +8,19 @@
  *
  * <p>
  * This is a {@code @FunctionalInterface} and may be used as a lambda
- * expression. Register
- * listeners via
+ * expression. Register listeners via
  * {@link dev.objz.commandbridge.api.CommandBridgeAPI#onServerConnected(ServerEventListener)}
  * and
  * {@link dev.objz.commandbridge.api.CommandBridgeAPI#onServerDisconnected(ServerEventListener)}.
  * Both methods return an {@link java.util.Optional} wrapping a
- * {@link dev.objz.commandbridge.api.message.Subscription}
- * on the Velocity proxy, and {@code Optional.empty()} on backend servers.
+ * {@link dev.objz.commandbridge.api.message.Subscription} on the Velocity
+ * proxy, and {@code Optional.empty()} on backend servers.
+ *
+ * <p>
+ * The listener receives the server that triggered the event:
  *
  * <pre>{@code
- * api.onServerConnected(server -> Log.info("Server connected: {}", server.id())).ifPresent(subscriptions::add);
+ * server -> Log.info("Server {}: {}", server.id(), server.type())
  * }</pre>
  *
  * @see dev.objz.commandbridge.api.CommandBridgeAPI#onServerConnected(ServerEventListener)

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

@@ -5,34 +5,17 @@
  * cancelled.
  *
  * <p>
- * When registering a listener via
+ * Returned by
  * {@link dev.objz.commandbridge.api.channel.MessageChannel#listen(dev.objz.commandbridge.api.message.MessageListener)}
- * or
- * {@link dev.objz.commandbridge.api.CommandBridgeAPI#onServerConnected(dev.objz.commandbridge.api.message.ServerEventListener)},
- * a {@code Subscription} is returned. The caller is responsible for storing it
- * and calling
- * {@link #cancel()} when the listener is no longer needed, for example during
- * plugin shutdown.
+ * and
+ * {@link dev.objz.commandbridge.api.CommandBridgeAPI#onServerConnected(dev.objz.commandbridge.api.message.ServerEventListener)}.
+ * The caller is responsible for storing it and calling {@link #cancel()} when
+ * the listener is no longer needed, for example during plugin shutdown.
  *
  * <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
- * Subscription sub = api.channel(CommandPayload.class)
- *         .listen((ctx, payload) -> handleCommand(ctx, payload));
- * }</pre>
- *
- * <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

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

@@ -11,21 +11,14 @@
  * A {@code PlayerLocator} is available only on the Velocity proxy. Obtain an
  * instance via
  * {@link dev.objz.commandbridge.api.CommandBridgeAPI#playerLocator()}. On
- * backend servers,
- * that method returns {@code Optional.empty()}.
+ * backend servers, that method returns {@code Optional.empty()}.
  *
  * <p>
- * The following example locates a player and sends a command to their current
- * server:
+ * To resolve a player's current server:
  *
  * <pre>{@code
- * api.playerLocator().ifPresent(locator -> {
- *     locator.locate(playerUUID).ifPresent(target -> {
- *         api.channel(CommandPayload.class)
- *                 .to(List.of(target))
- *                 .send(new CommandPayload("home", RunAs.PLAYER, playerUUID));
- *     });
- * });
+ * locator.locate(playerUUID).ifPresent(target ->
+ *         Log.info("Player is on server: {}", target.id()));
  * }</pre>
  *
  * @see dev.objz.commandbridge.api.CommandBridgeAPI#playerLocator()