feat: javadocing

Author: Jamalam360

common/src/client/java/io/github/jamalam360/jamlib/api/events/client/ClientPlayLifecycleEvents.java

@@ -1,6 +1,6 @@
 package io.github.jamalam360.jamlib.api.events.client;
 
-import io.github.jamalam360.jamlib.events.Event;
+import io.github.jamalam360.jamlib.api.events.Event;
 import net.minecraft.client.Minecraft;
 
 /**

…m360/jamlib/events/CancellableEvent.java …/jamlib/api/events/CancellableEvent.javacommon/src/main/java/io/github/jamalam360/jamlib/events/CancellableEvent.java renamed to common/src/main/java/io/github/jamalam360/jamlib/api/events/CancellableEvent.java common/src/main/java/io/github/jamalam360/jamlib/events/CancellableEvent.java renamed to common/src/main/java/io/github/jamalam360/jamlib/api/events/CancellableEvent.java

@@ -1,8 +1,18 @@
-package io.github.jamalam360.jamlib.events;
+package io.github.jamalam360.jamlib.api.events;
 
 import java.util.function.Function;
 
+/**
+ * A {@link Event} that can be canceled.
+ * @param <L> The listener type.
+ * @param <R> The return type.
+ */
 public class CancellableEvent<L, R> extends Event<L> {
+    /**
+	 * Invokes all listeners for this event.
+     * @param invoker The listener invoker.
+     * @return The result of the first listener to return a non-passing {@link EventResult}, or a passing {@link EventResult} if all listeners pass.
+     */
 	public EventResult<R> invokeCancellable(Function<L, EventResult<R>> invoker)  {
 		for (int priority : this.getListeners().keySet()) {
 			for (L listener : this.getListeners().get(priority)) {

…thub/jamalam360/jamlib/events/Event.java …/jamalam360/jamlib/api/events/Event.javacommon/src/main/java/io/github/jamalam360/jamlib/events/Event.java renamed to common/src/main/java/io/github/jamalam360/jamlib/api/events/Event.java common/src/main/java/io/github/jamalam360/jamlib/events/Event.java renamed to common/src/main/java/io/github/jamalam360/jamlib/api/events/Event.java

@@ -1,10 +1,14 @@
-package io.github.jamalam360.jamlib.events;
+package io.github.jamalam360.jamlib.api.events;
 
 import com.google.common.collect.Ordering;
 import com.google.common.collect.TreeMultimap;
 
 import java.util.function.Consumer;
 
+/**
+ * A listenable event.
+ * @param <L> The listener type.
+ */
 public class Event<L> {
 	public static final int DEFAULT_PRIORITY = 1000;
 	private final TreeMultimap<Integer, L> listeners;
@@ -13,14 +17,27 @@ public Event() {
 		this.listeners = TreeMultimap.create(Ordering.natural().reverse(), Ordering.arbitrary());
 	}
 
+    /**
+	 * Listens for this event, using the default priority of 1000.
+     * @param listener The listener.
+     */
 	public void listen(L listener) {
 		this.listen(DEFAULT_PRIORITY, listener);
 	}
 
+    /**
+	 * Listens for this event.
+     * @param priority The priority of the listener - higher numbers are executed first.
+     * @param listener The listener.
+     */
 	public void listen(int priority, L listener) {
 		this.listeners.put(priority, listener);
 	}
 
+    /**
+	 * Invokes all listeners for this event.
+     * @param invoker The listener invoker.
+     */
 	public void invoke(Consumer<L> invoker) {
 		for (int priority : this.listeners.keySet()) {
 			for (L listener : this.listeners.get(priority)) {

common/src/main/java/io/github/jamalam360/jamlib/api/events/EventResult.java

@@ -0,0 +1,50 @@
+package io.github.jamalam360.jamlib.api.events;
+
+import org.jetbrains.annotations.Nullable;
+
+/**
+ * The result of a {@link CancellableEvent}. Either passes or returns a value.
+ * @param <T> The returned value type.
+ */
+public class EventResult<T> {
+	private final boolean cancelled;
+	@Nullable
+	private final T result;
+
+	private EventResult(boolean cancelled, @Nullable T result) {
+		this.cancelled = cancelled;
+		this.result = result;
+	}
+
+    /**
+	 * Create a passing {@link EventResult}.
+     * @return A passing {@link EventResult}.
+     */
+	public static <T> EventResult<T> pass() {
+		return new EventResult<>(false, null);
+	}
+
+    /**
+	 * Create a cancelling {@link EventResult} with a result.
+     * @param result The result.
+     * @return A cancelling {@link EventResult} with the given result.
+     */
+	public static <T> EventResult<T> cancel(T result) {
+		return new EventResult<>(true, result);
+	}
+
+    /**
+     * @return Whether this {@link EventResult} indicates a cancellation.
+     */
+	public boolean wasCancelled() {
+		return this.cancelled;
+	}
+
+    /**
+     * @return The result of this {@link EventResult}, or null if it was not canceled.
+     */
+	@Nullable
+	public T getResult() {
+		return this.result;
+	}
+}

common/src/main/java/io/github/jamalam360/jamlib/api/network/Network.java

@@ -8,11 +8,20 @@
 
 import java.util.*;
 
+/**
+ * A platform-agnostic packet sending system.
+ */
 public class Network {
 	private static final Map<PayloadType<?>, NetworkPayloadType<?>> types = new HashMap<>();
 	private static final Map<PayloadType<?>, NetworkPayloadHandler<?>> clientBoundHandlers = new HashMap<>();
 	private static final Map<PayloadType<?>, NetworkPayloadHandler<?>> serverBoundHandlers = new HashMap<>();
 
+    /**
+	 * Registers a handler for a payload type.
+     * @param direction The direction the handler should be registered for.
+     * @param id The ID of the payload the handler handles.
+     * @param handler The handler.
+     */
 	public static <T> void registerHandler(Direction direction, PayloadType<T> id, NetworkPayloadHandler<T> handler) {
 		Map<PayloadType<?>, NetworkPayloadHandler<?>> handlers = switch (direction) {
 			case CLIENT_BOUND -> clientBoundHandlers;
@@ -26,6 +35,10 @@ public static <T> void registerHandler(Direction direction, PayloadType<T> id, N
 		handlers.put(id, handler);
 	}
 
+    /**
+     * @param id The ID of the payload type.
+     * @param type The type of the payload.
+     */
 	public static <T> void registerPayloadType(PayloadType<T> id, NetworkPayloadType<T> type) {
 		if (types.containsKey(id)) {
 			throw new IllegalArgumentException("A payload type with the id " + id + " is already registered");
@@ -35,6 +48,11 @@ public static <T> void registerPayloadType(PayloadType<T> id, NetworkPayloadType
 		JamLib.LOGGER.info("Registered network payload type {}", id.id());
 	}
 
+    /**
+	 * Sends a payload to the server.
+     * @param id The ID of the payload type.
+     * @param payload The payload.
+     */
 	@SuppressWarnings("unchecked")
 	public static <T> void sendToServer(PayloadType<T> id, T payload) {
 		if (!types.containsKey(id)) {
@@ -45,6 +63,11 @@ public static <T> void sendToServer(PayloadType<T> id, T payload) {
 		PlatformNetwork.sendToServer(id, type.getSerializer(), payload);
 	}
 
+	/**
+	 * Sends a payload to the client.
+	 * @param id The ID of the payload type.
+	 * @param payload The payload.
+	 */
 	@SuppressWarnings("unchecked")
 	public static <T> void sendToClient(ServerPlayer player, PayloadType<T> id, T payload) {
 		if (!types.containsKey(id)) {

common/src/main/java/io/github/jamalam360/jamlib/api/network/NetworkContext.java

@@ -2,5 +2,9 @@
 
 import net.minecraft.world.entity.player.Player;
 
+/**
+ * Context passed to a {@link NetworkPayloadHandler}.
+ * @param player The player who received or sent the packet.
+ */
 public record NetworkContext(Player player) {
 }

common/src/main/java/io/github/jamalam360/jamlib/api/network/NetworkPayloadHandler.java

@@ -1,6 +1,14 @@
 package io.github.jamalam360.jamlib.api.network;
 
+/**
+ * A handler for network payloads.
+ */
 @FunctionalInterface
 public interface NetworkPayloadHandler<T> {
+    /**
+	 * Handle an incoming network payload.
+     * @param ctx The network context.
+     * @param payload The payload.
+     */
 	void handle(NetworkContext ctx, T payload);
 }

common/src/main/java/io/github/jamalam360/jamlib/api/network/NetworkPayloadType.java

@@ -2,17 +2,45 @@
 
 import net.minecraft.network.RegistryFriendlyByteBuf;
 
+/**
+ * A payload that can be sent over the network.
+ * @param <T> The type of the payload, usually a record.
+ */
 public interface NetworkPayloadType<T> {
+    /**
+     * @return A serializer instance for the payload type.
+     */
 	Serializer<T> getSerializer();
+
+    /**
+     * @return A deserializer instance for the payload type.
+     */
 	Deserializer<T> getDeserializer();
 
+    /**
+	 * A serializer for a payload.
+     */
 	@FunctionalInterface
 	interface Serializer<T> {
+
+        /**
+		 * Serializes a payload to a buffer.
+         * @param object The payload to serialize.
+         * @param buf The buffer to write to.
+         */
 		void serialize(T object, RegistryFriendlyByteBuf buf);
 	}
 
+    /**
+	 * A deserializer for a payload.
+     */
 	@FunctionalInterface
 	interface Deserializer<T> {
+        /**
+		 * Deserializes a payload from a buffer.
+         * @param buf The buffer to read from.
+         * @return The deserialized payload.
+         */
 		T deserialize(RegistryFriendlyByteBuf buf);
 	}
 }

common/src/main/java/io/github/jamalam360/jamlib/api/network/PayloadType.java

@@ -2,5 +2,9 @@
 
 import net.minecraft.resources.Identifier;
 
+/**
+ * Uniquely identifies a {@link NetworkPayloadType}.
+ * @param id A unique identifier for the payload type.
+ */
 public record PayloadType<T>(Identifier id) {
 }

common/src/main/java/io/github/jamalam360/jamlib/api/network/StreamCodecNetworkPayloadType.java

@@ -3,6 +3,9 @@
 import net.minecraft.network.RegistryFriendlyByteBuf;
 import net.minecraft.network.codec.StreamCodec;
 
+/**
+ * A {@link NetworkPayloadType} that uses a {@link StreamCodec} to encode and decode the payload.
+ */
 public interface StreamCodecNetworkPayloadType<T> extends NetworkPayloadType<T> {
 	StreamCodec<RegistryFriendlyByteBuf, T> getStreamCodec();