Networking API javadoc fixes and small refactors

fabric-networking-api-v1/src/client/java/net/fabricmc/fabric/api/client/networking/v1/ClientConfigurationConnectionEvents.java

@@ -29,9 +29,9 @@
  * Offers access to events related to the configuration connection to a server on a logical client.
  */
 @ApiStatus.Experimental
-public class ClientConfigurationConnectionEvents {
+public final class ClientConfigurationConnectionEvents {
 	/**
-	 * Event indicating a connection entered the CONFIGURATION state, ready for registering channel handlers.
+	 * Event indicating a connection entering the CONFIGURATION state, ready for registering channel handlers.
 	 *
 	 * @see ClientConfigurationNetworking#registerReceiver(Identifier, ClientConfigurationNetworking.ConfigurationChannelHandler)
 	 */
@@ -63,6 +63,9 @@ public class ClientConfigurationConnectionEvents {
 		}
 	});
 
+	private ClientConfigurationConnectionEvents() {
+	}
+
 	@FunctionalInterface
 	public interface Init {
 		void onConfigurationInit(ClientConfigurationNetworkHandler handler, MinecraftClient client);

fabric-networking-api-v1/src/client/java/net/fabricmc/fabric/api/client/networking/v1/ClientConfigurationNetworking.java

@@ -39,7 +39,7 @@
 import net.fabricmc.fabric.mixin.networking.client.accessor.ClientCommonNetworkHandlerAccessor;
 
 /**
- * Offers access to configurtion stage client-side networking functionalities.
+ * Offers access to configuration stage client-side networking functionalities.
  *
  * <p>Client-side networking functionalities include receiving clientbound packets,
  * sending serverbound packets, and events related to client-side network handlers.

fabric-networking-api-v1/src/client/java/net/fabricmc/fabric/api/client/networking/v1/package-info.java

@@ -17,13 +17,31 @@
 /**
  * The Networking API (client side), version 1.
  *
- * <p>For login stage networking see {@link net.fabricmc.fabric.api.client.networking.v1.ClientLoginNetworking}.
- * For play stage networking see {@link net.fabricmc.fabric.api.client.networking.v1.ClientPlayNetworking}.
- *
- * <p>For events related to connection to a server see {@link net.fabricmc.fabric.api.client.networking.v1.ClientLoginConnectionEvents} for login stage
- * or {@link net.fabricmc.fabric.api.client.networking.v1.ClientPlayConnectionEvents} for play stage.
- *
- * <p>For events related to the ability of a server to receive packets on a channel of a specific name see {@link net.fabricmc.fabric.api.client.networking.v1.C2SPlayChannelEvents}.
+ * <p>There are three stages of Minecraft networking, all of which are supported in this API:
+ * <dl>
+ *     <dt>LOGIN</dt>
+ *     <dd>This is the initial stage, before the player logs into the world. If using a proxy server,
+ *     the packets in this stage may be intercepted and discarded by the proxy. <strong>Most of the pre-1.20.2
+ *     uses of this event should be replaced with the CONFIGURATION stage.</strong>
+ *     Related events are found at {@link net.fabricmc.fabric.api.client.networking.v1.ClientLoginConnectionEvents},
+ *     and related methods are found at {@link net.fabricmc.fabric.api.client.networking.v1.ClientLoginNetworking}.
+ *     </dd>
+ *     <dt>CONFIGURATION</dt>
+ *     <dd>This is the stage after LOGIN. The player is authenticated, but still hasn't joined the
+ *     world at this point. Clients can use this phase to send configurations or verify their mod
+ *     versions. Note that some server mods allow players in the PLAY stage to re-enter this stage,
+ *     for example when a player chooses a minigame server in a lobby.
+ *     Related events are found at {@link net.fabricmc.fabric.api.client.networking.v1.C2SConfigurationChannelEvents}
+ *     and {@link net.fabricmc.fabric.api.client.networking.v1.ClientConfigurationConnectionEvents}, and related methods are found at
+ *     {@link net.fabricmc.fabric.api.client.networking.v1.ClientConfigurationNetworking}.
+ *     </dd>
+ *     <dt>PLAY</dt>
+ *     <dd>This is the stage after CONFIGURATION, where gameplay-related packets are sent and received.
+ *     The player has joined the world and is playing the game. Related events are found at
+ *     {@link net.fabricmc.fabric.api.client.networking.v1.C2SPlayChannelEvents}
+ *     and {@link net.fabricmc.fabric.api.client.networking.v1.ClientPlayConnectionEvents}, and related methods are found at
+ *     {@link net.fabricmc.fabric.api.client.networking.v1.ClientPlayNetworking}.</dd>
+ * </dl>
  */
 
 package net.fabricmc.fabric.api.client.networking.v1;

fabric-networking-api-v1/src/main/java/net/fabricmc/fabric/api/networking/v1/FabricServerConfigurationNetworkHandler.java

@@ -26,13 +26,14 @@
  */
 public interface FabricServerConfigurationNetworkHandler {
 	/**
-	 * Enqueue a {@link ServerPlayerConfigurationTask} task to be processed.
+	 * Enqueues a {@link ServerPlayerConfigurationTask} task to be processed.
 	 *
 	 * <p>Before adding a task use {@link ServerConfigurationNetworking#canSend(ServerConfigurationNetworkHandler, Identifier)}
 	 * to ensure that the client can process this task.
 	 *
 	 * <p>Once the client has handled the task a packet should be sent to the server.
-	 * Upon receiving this packet the server should call {@link FabricServerConfigurationNetworkHandler#completeTask(ServerPlayerConfigurationTask.Key)}
+	 * Upon receiving this packet the server should call {@link FabricServerConfigurationNetworkHandler#completeTask(ServerPlayerConfigurationTask.Key)},
+	 * otherwise the client cannot join the world.
 	 *
 	 * @param task the task
 	 */
@@ -41,8 +42,10 @@ default void addTask(ServerPlayerConfigurationTask task) {
 	}
 
 	/**
+	 * Completes the task identified by {@code key}.
 	 *
-	 * @param key the key
+	 * @param key the task key
+	 * @throws IllegalStateException if the current task is not {@code key}
 	 */
 	default void completeTask(ServerPlayerConfigurationTask.Key key) {
 		throw new UnsupportedOperationException("Implemented via mixin");

fabric-networking-api-v1/src/main/java/net/fabricmc/fabric/api/networking/v1/PacketSender.java

@@ -21,6 +21,7 @@
 import io.netty.channel.ChannelFutureListener;
 import io.netty.util.concurrent.Future;
 import io.netty.util.concurrent.GenericFutureListener;
+import org.jetbrains.annotations.ApiStatus;
 import org.jetbrains.annotations.Nullable;
 
 import net.minecraft.network.PacketByteBuf;
@@ -35,6 +36,7 @@
  * Represents something that supports sending packets to channels.
  * @see PacketByteBufs
  */
+@ApiStatus.NonExtendable
 public interface PacketSender {
 	/**
 	 * Makes a packet for a channel.

fabric-networking-api-v1/src/main/java/net/fabricmc/fabric/api/networking/v1/PlayerLookup.java

@@ -39,7 +39,7 @@
 import net.fabricmc.fabric.mixin.networking.accessor.ThreadedAnvilChunkStorageAccessor;
 
 /**
- * For example, a block entity may use the methods in this class to send a packet to all clients which can see the block entity in order notify clients about a change.
+ * Helper methods to lookup players in a server.
  *
  * <p>The word "tracking" means that an entity/chunk on the server is known to a player's client (within in view distance) and the (block) entity should notify tracking clients of changes.
  *
@@ -117,8 +117,8 @@ public static Collection<ServerPlayerEntity> tracking(Entity entity) {
 
 			// return an immutable collection to guard against accidental removals.
 			if (tracker != null) {
-				return Collections.unmodifiableCollection(tracker.getPlayersTracking()
-						.stream().map(PlayerAssociatedNetworkHandler::getPlayer).collect(Collectors.toSet()));
+				return tracker.getPlayersTracking()
+						.stream().map(PlayerAssociatedNetworkHandler::getPlayer).collect(Collectors.toUnmodifiableSet());
 			}
 
 			return Collections.emptySet();

fabric-networking-api-v1/src/main/java/net/fabricmc/fabric/api/networking/v1/ServerConfigurationConnectionEvents.java

@@ -28,11 +28,11 @@
  * Offers access to events related to the connection to a client on a logical server while a client is configuring.
  */
 @ApiStatus.Experimental
-public class ServerConfigurationConnectionEvents {
+public final class ServerConfigurationConnectionEvents {
 	/**
 	 * Event fired before any vanilla configuration has taken place.
 	 *
-	 * <p>This event is executed on {@linkplain io.netty.channel.EventLoop netty's event loops}
+	 * <p>This event is executed on {@linkplain io.netty.channel.EventLoop netty's event loops}.
 	 *
 	 * <p>Task queued during this event will complete before vanilla configuration starts.
 	 */
@@ -45,7 +45,7 @@ public class ServerConfigurationConnectionEvents {
 	/**
 	 * Event fired during vanilla configuration.
 	 *
-	 * <p>This event is executed on {@linkplain io.netty.channel.EventLoop netty's event loops}
+	 * <p>This event is executed on {@linkplain io.netty.channel.EventLoop netty's event loops}.
 	 *
 	 * <p>An example usage of this:
 	 * <pre>{@code
@@ -76,6 +76,9 @@ public class ServerConfigurationConnectionEvents {
 		}
 	});
 
+	private ServerConfigurationConnectionEvents() {
+	}
+
 	@FunctionalInterface
 	public interface Configure {
 		void onSendConfiguration(ServerConfigurationNetworkHandler handler, MinecraftServer server);

fabric-networking-api-v1/src/main/java/net/fabricmc/fabric/api/networking/v1/ServerLoginNetworking.java

@@ -20,6 +20,7 @@
 import java.util.Set;
 import java.util.concurrent.Future;
 
+import org.jetbrains.annotations.ApiStatus;
 import org.jetbrains.annotations.Nullable;
 
 import net.minecraft.network.PacketByteBuf;
@@ -151,10 +152,9 @@ public interface LoginQueryResponseHandler {
 
 	/**
 	 * Allows blocking client log-in until all futures passed into {@link LoginSynchronizer#waitFor(Future)} are completed.
-	 *
-	 * @apiNote this interface is not intended to be implemented by users of api.
 	 */
 	@FunctionalInterface
+	@ApiStatus.NonExtendable
 	public interface LoginSynchronizer {
 		/**
 		 * Allows blocking client log-in until the {@code future} is {@link Future#isDone() done}.

fabric-networking-api-v1/src/main/java/net/fabricmc/fabric/api/networking/v1/package-info.java

@@ -17,13 +17,35 @@
 /**
  * The Networking API, version 1.
  *
- * <p>For login stage networking see {@link net.fabricmc.fabric.api.networking.v1.ServerLoginNetworking}.
- * For play stage networking see {@link net.fabricmc.fabric.api.networking.v1.ServerPlayNetworking}.
+ * <p>There are three stages of Minecraft networking, all of which are supported in this API:
+ * <dl>
+ *     <dt>LOGIN</dt>
+ *     <dd>This is the initial stage, before the player logs into the world. If using a proxy server,
+ *     the packets in this stage may be intercepted and discarded by the proxy. <strong>Most of the pre-1.20.2
+ *     uses of this event should be replaced with the CONFIGURATION stage.</strong>
+ *     Related events are found at {@link net.fabricmc.fabric.api.networking.v1.ServerLoginConnectionEvents},
+ *     and related methods are found at {@link net.fabricmc.fabric.api.networking.v1.ServerLoginNetworking}.
+ *     </dd>
+ *     <dt>CONFIGURATION</dt>
+ *     <dd>This is the stage after LOGIN. The player is authenticated, but still hasn't joined the
+ *     world at this point. Servers can use this phase to send configurations or verify client's mod
+ *     versions. Note that some server mods allow players in the PLAY stage to re-enter this stage,
+ *     for example when a player chooses a minigame server in a lobby.
+ *     Related events are found at {@link net.fabricmc.fabric.api.networking.v1.S2CConfigurationChannelEvents}
+ *     {@link net.fabricmc.fabric.api.networking.v1.ServerConfigurationConnectionEvents}, and related methods are found at
+ *     {@link net.fabricmc.fabric.api.networking.v1.ServerConfigurationNetworking}.
+ *     </dd>
+ *     <dt>PLAY</dt>
+ *     <dd>This is the stage after CONFIGURATION, where gameplay-related packets are sent and received.
+ *     The player has joined the world and is playing the game. Related events are found at
+ *     {@link net.fabricmc.fabric.api.networking.v1.S2CPlayChannelEvents}
+ *     and {@link net.fabricmc.fabric.api.networking.v1.ServerPlayConnectionEvents}, and related methods are found at
+ *     {@link net.fabricmc.fabric.api.networking.v1.ServerPlayNetworking}.</dd>
+ * </dl>
  *
- * <p>For events related to the connection to a client see {@link net.fabricmc.fabric.api.networking.v1.ServerLoginConnectionEvents} for login stage
- * or {@link net.fabricmc.fabric.api.networking.v1.ServerPlayConnectionEvents} for play stage.
- *
- * <p>For events related to the ability of a client to receive packets on a channel of a specific name see {@link net.fabricmc.fabric.api.networking.v1.S2CPlayChannelEvents}.
+ * <p>In addition, this API includes helpers for {@linkplain
+ * net.fabricmc.fabric.api.networking.v1.PacketByteBufs buffer creations} and {@linkplain
+ * net.fabricmc.fabric.api.networking.v1.PlayerLookup player lookups}.
  */
 
 package net.fabricmc.fabric.api.networking.v1;