Events and package JavaDocs

Author: Jonathing

src/main/java/module-info.java

@@ -2,8 +2,17 @@
  * Copyright (c) Forge Development LLC
  * SPDX-License-Identifier: LGPL-2.1-only
  */
+
 import org.jspecify.annotations.NullMarked;
 
+/**
+ * The EventBus module is split into two distinct packages: the {@linkplain net.minecraftforge.eventbus.api API} and the
+ * {@linkplain net.minecraftforge.eventbus.internal internal implementation}. The API contains the interfaces for
+ * consumers to interact with. The internal implementation is never exported and should not be accessed as it can be
+ * changed at any time, without prior warning, and for any reason.
+ *
+ * @see net.minecraftforge.eventbus.api
+ */
 @NullMarked
 module net.minecraftforge.eventbus {
     requires java.logging;

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

@@ -16,6 +16,12 @@
  * A collection of {@link EventBus} instances that are grouped together for easier management.
  */
 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.
+     *
+     * @see #create(String)
+     */
     BusGroup DEFAULT = create("default");
 
     /**
@@ -37,6 +43,7 @@ static BusGroup create(String name) {
      * @throws IllegalArgumentException If a BusGroup with the given name already exists
      * @apiNote In theory, it is possible to use any base type when creating a BusGroup. However, it is recommended to
      * either use a direct subtype of {@link Event} or use {@link #create(String)} which uses the default type.
+     * @see #create(String)
      */
     static BusGroup create(String name, Class<?> baseType) {
         return new BusGroupImpl(name, baseType);

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

@@ -2,6 +2,12 @@
  * Copyright (c) Forge Development LLC
  * SPDX-License-Identifier: LGPL-2.1-only
  */
+/**
+ * This package houses classes related to bus-specific APIs, such as
+ * {@link net.minecraftforge.eventbus.api.bus.BusGroup BusGroup} and
+ * {@link net.minecraftforge.eventbus.api.bus.EventBus}. These APIs are documented in extensive detail within their
+ * respective classes.
+ */
 @NullMarked
 package net.minecraftforge.eventbus.api.bus;
 

src/main/java/net/minecraftforge/eventbus/api/event/InheritableEvent.java

@@ -6,4 +6,13 @@
 
 import net.minecraftforge.eventbus.internal.Event;
 
+/**
+ * This top-level event implementation exists as a bare interface to allow events to implement it however they wish.
+ * Unlike {@link MutableEvent}, which is an object that must be extended from, InheritableEvent can be applied to any
+ * type that needs to have information sent to listeners via an
+ * {@linkplain net.minecraftforge.eventbus.api.bus.EventBus event bus}.
+ *
+ * @see MutableEvent
+ * @see RecordEvent
+ */
 public non-sealed interface InheritableEvent extends Event {}

src/main/java/net/minecraftforge/eventbus/api/event/MutableEvent.java

@@ -7,4 +7,16 @@
 import net.minecraftforge.eventbus.internal.Event;
 import net.minecraftforge.eventbus.internal.MutableEventInternals;
 
+/**
+ * This top-level event implementation exists as a base object that can be expanded upon to contain information to be
+ * sent to listeners via an {@linkplain net.minecraftforge.eventbus.api.bus.EventBus event bus}.
+ * <p>The primary difference between MutableEvent and {@link InheritableEvent} is that MutableEvent is
+ * {@linkplain net.minecraftforge.eventbus.api.event.characteristic.MonitorAware monitor-aware}. Although it is the
+ * MonitorAware interface that enforces this contract, its default implementation works natively with MutableEvent
+ * without needing any additional implementations from the consumer.</p>
+ *
+ * @see net.minecraftforge.eventbus.api.event.characteristic.MonitorAware MonitorAware
+ * @see InheritableEvent
+ * @see RecordEvent
+ */
 public non-sealed abstract class MutableEvent extends MutableEventInternals implements Event {}

src/main/java/net/minecraftforge/eventbus/api/event/RecordEvent.java

@@ -6,4 +6,15 @@
 
 import net.minecraftforge.eventbus.internal.Event;
 
+/**
+ * This top-level implementation is for records to directly implement. This is enforced at runtime, as any non-record
+ * event that implements this interface will cause an {@link IllegalArgumentException} to be thrown when an
+ * {@linkplain net.minecraftforge.eventbus.api.bus.EventBus event bus} is created for it.
+ *
+ * @apiNote Although records can inherit {@link InheritableEvent} without implementing RecordEvent, it is highly
+ * recommended to implement this instead as it will boost performance drastically. EventBus is designed to take
+ * advantage of the finalized state of records.
+ * @see InheritableEvent
+ * @see MutableEvent
+ */
 public non-sealed interface RecordEvent extends Event {}

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

@@ -8,7 +8,13 @@
 import net.minecraftforge.eventbus.internal.Event;
 
 /**
- * A cancellable event returns {@code true} from {@link CancellableEventBus#post(Event)} if it was cancelled.
- * <p>When an event is cancelled, it will not be passed to any further non-monitor listeners.</p>
+ * A cancellable event returns {@code true} from {@link CancellableEventBus#post(Event)} if it was cancelled. The
+ * following key points must be known regarding cancellable events:
+ * <ul>
+ *     <li>When an event is cancelled, it will not be passed to any further non-{@linkplain net.minecraftforge.eventbus.api.listener.Priority#MONITOR monitor} listeners.</li>
+ *     <li>Cancellable events <strong>must be used with a {@linkplain CancellableEventBus cancellable event bus}</strong> in order to function as intended.</li>
+ * </ul>
+ *
+ * @see CancellableEventBus
  */
 public non-sealed interface Cancellable extends EventCharacteristic {}

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

@@ -8,10 +8,13 @@
 import net.minecraftforge.eventbus.internal.MutableEventInternals;
 
 /**
- * Experimental feature - may be removed, renamed or otherwise changed without notice.
- * <p>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.</p>
+ * 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.
  * <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
+ * notice.</strong>
+ * @see MutableEvent
  */
 public non-sealed interface MonitorAware extends EventCharacteristic {
     default boolean isMonitoring() {

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

@@ -8,9 +8,9 @@
 import net.minecraftforge.eventbus.internal.Event;
 
 /**
- * Experimental feature - may be removed, renamed or otherwise changed without notice.
- * <p>{@link SelfPosting} events are associated with a default {@link EventBus} in order to offer some convenience
- * instance methods.</p>
+ * Self-posting events are associated with a default {@link EventBus} in order to offer some convenience
+ * instance methods.
+ * <p>
  * <u>Example</u>
  * {@snippet :
  * import net.minecraftforge.eventbus.api.event.RecordEvent;
@@ -31,6 +31,8 @@
  * // instead of this
  * ExampleEvent.BUS.post(new ExampleEvent());
  *}
+ * @apiNote <strong>This feature is experimental - it may be removed, renamed or otherwise changed without
+ * notice.</strong>
  */
 public non-sealed interface SelfPosting<T extends Event> extends EventCharacteristic {
     /**

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

@@ -2,6 +2,10 @@
  * Copyright (c) Forge Development LLC
  * SPDX-License-Identifier: LGPL-2.1-only
  */
+/**
+ * This package houses classes related to the characterists that
+ * {@linkplain net.minecraftforge.eventbus.internal.Event events} can have.
+ */
 @NullMarked
 package net.minecraftforge.eventbus.api.event.characteristic;