From 82c66c45ec4c71226dd784cbb3ec2f78e5ea754d Mon Sep 17 00:00:00 2001
From: kske <kai@kske.dev>
Date: Mon, 1 Nov 2021 09:42:12 +0100
Subject: [PATCH 1/2] Improve EventBus Javadoc, make EventBusException final

---
 .../java/dev/kske/eventbus/core/EventBus.java | 37 +++++++++++++++----
 .../kske/eventbus/core/EventBusException.java | 12 ++++--
 pom.xml                                       |  2 +-
 3 files changed, 38 insertions(+), 13 deletions(-)

diff --git a/event-bus-core/src/main/java/dev/kske/eventbus/core/EventBus.java b/event-bus-core/src/main/java/dev/kske/eventbus/core/EventBus.java
index 3eef15c..3d8113d 100644
--- a/event-bus-core/src/main/java/dev/kske/eventbus/core/EventBus.java
+++ b/event-bus-core/src/main/java/dev/kske/eventbus/core/EventBus.java
@@ -66,11 +66,27 @@ public final class EventBus {
 		return singletonInstance;
 	}
 
-	private final Map<Class<?>, TreeSet<EventHandler>>	bindings			=
-		new ConcurrentHashMap<>();
-	private final Set<Object>							registeredListeners	=
-		ConcurrentHashMap.newKeySet();
-	private final ThreadLocal<DispatchState>			dispatchState		=
+	/**
+	 * Event handler bindings (target class to handlers registered for that class), does not contain
+	 * other (polymorphic) handlers.
+	 *
+	 * @since 0.0.1
+	 */
+	private final Map<Class<?>, TreeSet<EventHandler>> bindings = new ConcurrentHashMap<>();
+
+	/**
+	 * Registered listeners.
+	 *
+	 * @since 0.0.1
+	 */
+	private final Set<Object> registeredListeners = ConcurrentHashMap.newKeySet();
+
+	/**
+	 * Thread-local dispatch state.
+	 *
+	 * @since 0.1.0
+	 */
+	private final ThreadLocal<DispatchState> dispatchState =
 		ThreadLocal.withInitial(DispatchState::new);
 
 	/**
@@ -78,7 +94,8 @@ public final class EventBus {
 	 * priority.
 	 *
 	 * @param event the event to dispatch
-	 * @throws EventBusException if an event handler isn't accessible or has an invalid signature
+	 * @throws EventBusException    if an event handler isn't accessible or has an invalid signature
+	 * @throws NullPointerException if the specified event is {@code null}
 	 * @since 0.0.1
 	 */
 	public void dispatch(Object event) throws EventBusException {
@@ -173,8 +190,9 @@ public final class EventBus {
 	 * Registers an event listener at this event bus.
 	 *
 	 * @param listener the listener to register
-	 * @throws EventBusException if the listener is already registered or a declared event handler
-	 *                           does not comply with the specification
+	 * @throws EventBusException    if the listener is already registered or a declared event
+	 *                              handler does not comply with the specification
+	 * @throws NullPointerException if the specified listener is {@code null}
 	 * @since 0.0.1
 	 * @see Event
 	 */
@@ -229,6 +247,7 @@ public final class EventBus {
 		Objects.requireNonNull(listener);
 		logger.log(Level.INFO, "Removing event listener {0}", listener.getClass().getName());
 
+		// Remove bindings from binding map
 		for (var binding : bindings.values()) {
 			var it = binding.iterator();
 			while (it.hasNext()) {
@@ -239,6 +258,8 @@ public final class EventBus {
 				}
 			}
 		}
+
+		// Remove the listener itself
 		registeredListeners.remove(listener);
 	}
 
diff --git a/event-bus-core/src/main/java/dev/kske/eventbus/core/EventBusException.java b/event-bus-core/src/main/java/dev/kske/eventbus/core/EventBusException.java
index d67616c..959cbff 100644
--- a/event-bus-core/src/main/java/dev/kske/eventbus/core/EventBusException.java
+++ b/event-bus-core/src/main/java/dev/kske/eventbus/core/EventBusException.java
@@ -1,14 +1,18 @@
 package dev.kske.eventbus.core;
 
 /**
- * This runtime exception is thrown when an event bus error occurs. This can
- * either occur while registering event listeners with invalid handlers, or when
- * an event handler throws an exception.
+ * This unchecked exception is specific to the event bus and can be thrown under the following
+ * circumstances:
+ * <ul>
+ * <li>An event handler throws an exception (which is stores as the cause)</li>
+ * <li>An event listener with an invalid event handler is registered</li>
+ * <li>{@link EventBus#cancel()} is invoked from outside an active dispatch thread</li>
+ * </ul>
  *
  * @author Kai S. K. Engelbart
  * @since 0.0.1
  */
-public class EventBusException extends RuntimeException {
+public final class EventBusException extends RuntimeException {
 
 	private static final long serialVersionUID = 1L;
 
diff --git a/pom.xml b/pom.xml
index 965c03f..50b750f 100644
--- a/pom.xml
+++ b/pom.xml
@@ -9,7 +9,7 @@
 	<packaging>pom</packaging>
 
 	<name>Event Bus</name>
-	<description>An event handling framework for Java utilizing annotations.</description>
+	<description>An event handling library for Java utilizing annotations.</description>
 	<url>https://git.kske.dev/kske/event-bus</url>
 
 	<modules>
-- 
2.45.2


From 872b3953745a29cec3dbc6268e4c715b9d0f7517 Mon Sep 17 00:00:00 2001
From: kske <kai@kske.dev>
Date: Mon, 1 Nov 2021 20:52:14 +0100
Subject: [PATCH 2/2] Rephrase some Javadoc

As suggested by @delvh.
---
 .../src/main/java/dev/kske/eventbus/core/EventBus.java       | 5 +++--
 .../main/java/dev/kske/eventbus/core/EventBusException.java  | 2 +-
 2 files changed, 4 insertions(+), 3 deletions(-)

diff --git a/event-bus-core/src/main/java/dev/kske/eventbus/core/EventBus.java b/event-bus-core/src/main/java/dev/kske/eventbus/core/EventBus.java
index 3d8113d..44ff01c 100644
--- a/event-bus-core/src/main/java/dev/kske/eventbus/core/EventBus.java
+++ b/event-bus-core/src/main/java/dev/kske/eventbus/core/EventBus.java
@@ -75,14 +75,15 @@ public final class EventBus {
 	private final Map<Class<?>, TreeSet<EventHandler>> bindings = new ConcurrentHashMap<>();
 
 	/**
-	 * Registered listeners.
+	 * Stores all registered event listeners (which declare event handlers) and prevents them from
+	 * being garbage collected.
 	 *
 	 * @since 0.0.1
 	 */
 	private final Set<Object> registeredListeners = ConcurrentHashMap.newKeySet();
 
 	/**
-	 * Thread-local dispatch state.
+	 * The current event dispatching state, local to each thread.
 	 *
 	 * @since 0.1.0
 	 */
diff --git a/event-bus-core/src/main/java/dev/kske/eventbus/core/EventBusException.java b/event-bus-core/src/main/java/dev/kske/eventbus/core/EventBusException.java
index 959cbff..618a24a 100644
--- a/event-bus-core/src/main/java/dev/kske/eventbus/core/EventBusException.java
+++ b/event-bus-core/src/main/java/dev/kske/eventbus/core/EventBusException.java
@@ -4,7 +4,7 @@ package dev.kske.eventbus.core;
  * This unchecked exception is specific to the event bus and can be thrown under the following
  * circumstances:
  * <ul>
- * <li>An event handler throws an exception (which is stores as the cause)</li>
+ * <li>An event handler throws an exception (which is stored as the cause)</li>
  * <li>An event listener with an invalid event handler is registered</li>
  * <li>{@link EventBus#cancel()} is invoked from outside an active dispatch thread</li>
  * </ul>
-- 
2.45.2