API (hopefully) done

Author: Jonathing

src/main/java/net/minecraftforge/eventbus/api/bus/BusGroup.java

@@ -17,8 +17,8 @@
  */
 public sealed interface BusGroup permits BusGroupImpl {
     /**
-     * The default BusGroup provided by EventBus. While it is recommended to create your own BusGroup, this can be used
-     * as a safe default if necessary.
+     * The default BusGroup provided by EventBus. If when creating an {@link EventBus} the BusGroup is not specified, it
+     * will be registered in this one.
      *
      * @see #create(String)
      */

src/main/java/net/minecraftforge/eventbus/api/bus/CancellableEventBus.java

@@ -70,8 +70,8 @@ public sealed interface CancellableEventBus<T extends Event & Cancellable>
      *                         breaking changes if the event is no longer cancellable in the future.</p>
      * @param listener The listener to add.
      * @return A reference that can be used to remove this listener later with {@link #removeListener(EventListener)}.
-     * @see #addListener(Predicate) For adding a listener that can cancel the event conditionally
-     * @see #addListener(Consumer) For adding a listener that never cancels the event
+     * @see #addListener(Predicate)
+     * @see #addListener(Consumer)
      */
     default EventListener addListener(boolean alwaysCancelling, Consumer<T> listener) {
         return addListener(Priority.NORMAL, alwaysCancelling, listener);
@@ -85,7 +85,7 @@ default EventListener addListener(boolean alwaysCancelling, Consumer<T> listener
      *                         unnecessary breaking changes if the event is no longer cancellable in the future</p>
      * @param listener The listener to add.
      * @return A reference that can be used to remove this listener later with {@link #removeListener(EventListener)}.
-     * @see Priority For common priority values
+     * @see Priority
      */
     EventListener addListener(byte priority, boolean alwaysCancelling, Consumer<T> listener);
 
@@ -101,18 +101,35 @@ default EventListener addListener(boolean alwaysCancelling, Consumer<T> listener
      * @param priority The priority of this listener. Higher numbers are called first.
      * @param listener The listener to add.
      * @return A reference that can be used to remove this listener later with {@link #removeListener(EventListener)}.
-     * @see Priority For common priority values
+     * @see Priority
      */
     EventListener addListener(byte priority, Predicate<T> listener);
 
-    // MONITORING
+    /**
+     * Adds a monitoring listener to this EventBus with an unchanging priority of {@link Priority#MONITOR}.
+     * @param listener The listener to add.
+     * @return A reference that can be used to remove this listener later with {@link #removeListener(EventListener)}.
+     * @see Priority#MONITOR
+     */
     EventListener addListener(ObjBooleanBiConsumer<T> listener);
 
+    /**
+     * Creates a new CancellableEventBus for the given event type on the {@linkplain BusGroup#DEFAULT default} {@link BusGroup}.
+     * @param eventType The type of event the bus will have
+     * @param <T> The type of event
+     * @return The new CancallableEventBus
+     */
     @SuppressWarnings("ClassEscapesDefinedScope") // E can be a subtype of Event which is publicly accessible
     static <T extends Event & Cancellable> CancellableEventBus<T> create(Class<T> eventType) {
         return create(BusGroup.DEFAULT, eventType);
     }
 
+    /**
+     * Creates a new CancellableEventBus for the given event type on the given BusGroup.
+     * @param eventType The type of event the bus will have
+     * @param <T> The type of event
+     * @return The new CancallableEventBus
+     */
     @SuppressWarnings("ClassEscapesDefinedScope") // E can be a subtype of Event which is publicly accessible
     static <T extends Event & Cancellable> CancellableEventBus<T> create(BusGroup busGroup, Class<T> eventType) {
         return (CancellableEventBus<T>) ((BusGroupImpl) busGroup).getOrCreateEventBus(eventType);

src/main/java/net/minecraftforge/eventbus/api/bus/EventBus.java

@@ -113,7 +113,7 @@ public sealed interface EventBus<T extends Event> permits CancellableEventBus, A
     boolean hasListeners();
 
     /**
-     * Creates a new EventBus for the given event type on the default {@link BusGroup}.
+     * Creates a new EventBus for the given event type on the {@linkplain BusGroup#DEFAULT default} {@link BusGroup}.
      * <p><strong>Important:</strong> The returned EventBus <i>MUST</i> be stored in a {@code static final} field -
      * failing to do so will severely hurt performance.</p>
      * @apiNote There can only be one EventBus instance per event type per BusGroup.

src/main/java/net/minecraftforge/eventbus/api/event/characteristic/MonitorAware.java

@@ -8,8 +8,9 @@
 import net.minecraftforge.eventbus.internal.MutableEventInternals;
 
 /**
- * Events that are {@link MonitorAware} can provide stronger immutability guarantees to monitor listeners by returning
- * unmodifiable views or throwing exceptions on mutation attempts when monitoring.
+ * Events that are {@link MonitorAware} can provide stronger immutability guarantees to
+ * {@linkplain net.minecraftforge.eventbus.api.listener.Priority#MONITOR monitor} listeners by returning unmodifiable
+ * views or throwing exceptions on mutation attempts when monitoring.
  * <p>Only supported for {@link MutableEvent} at this time.</p>
  *
  * @apiNote <strong>This feature is experimental - it may be removed, renamed or otherwise changed without

src/main/java/net/minecraftforge/eventbus/api/listener/EventListener.java

@@ -12,11 +12,13 @@
 import java.util.function.Consumer;
 
 /**
- * Users can retain instances of this interface to remove listeners that were previously added to the same
- * {@link EventBus}.You can obtain instances of this interface by calling any of the {@code addListener} methods
- * on an EventBus, such as {@link EventBus#addListener(Consumer)}.
- * <p>Internally, this acts as a wrapper over lambdas to give them identity, enrich debug info and to allow
- * various conversion operations to different lambda types.</p>
+ * Users can retain instances of this interface to {@linkplain EventBus#removeListener(EventListener) remove listeners}
+ * that were previously added to the same {@link EventBus}. You can obtain instances of this interface by calling any of
+ * the {@code addListener} methods on an EventBus, such as {@link EventBus#addListener(Consumer)}.
+ *
+ * @implNote Internally, this acts as a wrapper over lambdas to give them identity, enrich debug info and to allow
+ * various conversion operations to different lambda types.
+ * @see EventBus
  */
 public sealed interface EventListener permits EventListenerImpl {
     @SuppressWarnings("ClassEscapesDefinedScope") // ? can be a subtype of Event which is publicly accessible

src/main/java/net/minecraftforge/eventbus/api/listener/ObjBooleanBiConsumer.java

@@ -7,9 +7,15 @@
 import java.util.function.BiConsumer;
 
 /**
- * A {@link BiConsumer} that takes an object and a primitive boolean, to avoid boxing.
+ * A {@link BiConsumer} that takes an object and a primitive boolean, to avoid boxing. Used for
+ * {@linkplain net.minecraftforge.eventbus.api.listener.Priority#MONITOR monitor} listeners.
  */
 @FunctionalInterface
 public interface ObjBooleanBiConsumer<T> {
+    /**
+     * @param obj The object of type {@link T}, usually an event.
+     * @param bool The boolean value, usually an event's cancelled status.
+     * @see BiConsumer#accept(Object, Object)
+     */
     void accept(T obj, boolean bool);
 }

src/main/java/net/minecraftforge/eventbus/api/listener/SubscribeEvent.java

@@ -4,20 +4,136 @@
  */
 package net.minecraftforge.eventbus.api.listener;
 
+import net.minecraftforge.eventbus.api.bus.BusGroup;
+import net.minecraftforge.eventbus.api.bus.CancellableEventBus;
+import net.minecraftforge.eventbus.api.bus.EventBus;
 import net.minecraftforge.eventbus.api.event.characteristic.Cancellable;
 
-import java.lang.annotation.*;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Inherited;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+import java.util.function.Consumer;
 
+/**
+ * This annotation is used to mark methods as event handlers. The contract for the method that has this annotation
+ * applied is the same as if it was treated as a lambda and fed into {@link EventBus#addListener(Consumer)} or one of
+ * its sister methods from {@link CancellableEventBus} that accept a {@linkplain java.util.function.Predicate predicate}
+ * or {@linkplain ObjBooleanBiConsumer object-boolean bi-consumer}.
+ * <p>Classes that contain methods annotated with SubscribeEvent must be registered with the applicable
+ * {@link BusGroup}.</p>
+ * {@snippet :
+ * import net.minecraftforge.eventbus.api.event.InheritableEvent;
+ * import java.lang.invoke.MethodHandles;
+ *
+ * // in MyEvent.java
+ * public class MyEvent implements InheritableEvent {
+ *     public static final EventBus<MyEvent> BUS = EventBus.create(Main.GROUP, MyEvent.class);
+ * }
+ *
+ * // in MyClass.java
+ * public class MyClass {
+ *     @SubscribeEvent
+ *     public static void onEvent(MyEvent event) {
+ *         System.out.println("Hello! I exist!");
+ *     }
+ *
+ *     @SubscribeEvent(priority = Priority.LOW)
+ *     public static void onEventLater(MyEvent event) {
+ *         System.out.println("I also exist! But am called slightly later!");
+ *     }
+ *
+ *     public static void init() {
+ *         Main.GROUP.register(MethodHandles.lookup(), MyClass.class);
+ *     }
+ * }
+ *
+ * // in Main.java
+ * public class Main {
+ *     public static final BusGroup GROUP = BusGroup.create("my_group");
+ *
+ *     public static void main(String[] args) {
+ *         MyClass.init();
+ *     }
+ * }
+ *}
+ *
+ * <p>The same can also be done for cancellable events. As mentioned earlier, shaping the targeted method in the form
+ * of a predicate or object-boolean bi-consumer will yield the same results when registered with a BusGroup</p>
+ * {@snippet :
+ * import net.minecraftforge.eventbus.api.event.MutableEvent;
+ * import net.minecraftforge.eventbus.api.event.characteristic.MonitorAware;
+ * import java.lang.invoke.MethodHandles;
+ *
+ * // in MyEvent.java
+ * public class MyCancellableEvent extends MutableEvent implements MonitorAware {
+ *     public static final CancellableEventBus<MyEvent> BUS = CancellableEventBus.create(Main.GROUP, MyCancellableEvent.class);
+ *
+ *     private boolean somethingImportant = true;
+ *
+ *     public void setSomethingImportant(boolean value) {
+ *         if (!this.isMonitoring())
+ *             this.somethingImportant = value;
+ *     }
+ * }
+ *
+ * // in MyClass.java
+ * public class MyClass {
+ *     @SubscribeEvent
+ *     public static boolean onEvent(MyCancellableEvent event) {
+ *         System.out.println("Hello! I exist!");
+ *         System.out.println("Hello! I will not cancel this event!");
+ *         return false;
+ *     }
+ *
+ *     @SubscribeEvent(priority = Priority.LOW, alwaysCancelling = true)
+ *     public static void onEventLater(MyCancellableEvent event) {
+ *         System.out.println("I also exist! But I will cancel this event!");
+ *     }
+ *
+ *     @SubscribeEvent(priority = Priority.LOWEST)
+ *     public static void onEventLatest(MyCancellableEvent event) {
+ *         System.out.println("I don't exist! I can't run because the event's been cancelled!");
+ *     }
+ *
+ *     @SubscribeEvent // because this is an object-boolean bi-consumer, priority is implicitly MONITOR
+ *     public static void onEventMonitoring(MyCancellableEvent event, boolean cancelled) {
+ *         System.out.println("I exist! I'm a monitoring listener and will always run!");
+ *         // this won't do anything:
+ *         event.setSomethingImportant(false);
+ *     }
+ *
+ *     public static void init() {
+ *         Main.GROUP.register(MethodHandles.lookup(), MyClass.class);
+ *     }
+ * }
+ *
+ * // in Main.java
+ * public class Main {
+ *     public static final BusGroup GROUP = BusGroup.create("my_group");
+ *
+ *     public static void main(String[] args) {
+ *         MyClass.init();
+ *     }
+ * }
+ *}
+ */
 @Inherited
 @Target(ElementType.METHOD)
 @Retention(RetentionPolicy.RUNTIME)
 public @interface SubscribeEvent {
+    /**
+     * @return The priority of the listener.
+     * @see Priority
+     */
     byte priority() default Priority.NORMAL;
 
     /**
      * If the event is cancellable, setting this to true will make the listener always cancel the event.
      *
-     * @implSpec If true, the annotated method must return {@code void} and the event must implement {@link Cancellable}.
+     * @implSpec If true, the annotated method must return {@code void} and the event must implement
+     * {@link Cancellable}.
      */
     boolean alwaysCancelling() default false;
 }

src/main/java/net/minecraftforge/eventbus/api/listener/package-info.java

@@ -2,6 +2,11 @@
  * Copyright (c) Forge Development LLC
  * SPDX-License-Identifier: LGPL-2.1-only
  */
+/**
+ * This package houses classes related to listener-specific APIs. These interfaces are usually consumed as part of usage
+ * of the {@linkplain net.minecraftforge.eventbus.api.bus event bus} and
+ * {@linkplain net.minecraftforge.eventbus.api.event event} APIs.
+ */
 @NullMarked
 package net.minecraftforge.eventbus.api.listener;