From ef572c43c7948988214df0363c1e6084265dd6fe Mon Sep 17 00:00:00 2001
From: OLEGSHA <kvadropups@gmail.com>
Date: Thu, 25 Mar 2021 17:15:03 +0300
Subject: [PATCH] Updated documentation for GuavaEventBusHijacker and
 ReportingEventBus

---
 .../common/hacks/GuavaEventBusHijacker.java   | 19 +++++++++----------
 .../common/util/crash/ReportingEventBus.java  | 18 +++++++++++++++++-
 2 files changed, 26 insertions(+), 11 deletions(-)

diff --git a/src/main/java/ru/windcorp/progressia/common/hacks/GuavaEventBusHijacker.java b/src/main/java/ru/windcorp/progressia/common/hacks/GuavaEventBusHijacker.java
index 6bc7901..8ee2c60 100644
--- a/src/main/java/ru/windcorp/progressia/common/hacks/GuavaEventBusHijacker.java
+++ b/src/main/java/ru/windcorp/progressia/common/hacks/GuavaEventBusHijacker.java
@@ -15,7 +15,7 @@
  * You should have received a copy of the GNU General Public License
  * along with this program.  If not, see <https://www.gnu.org/licenses/>.
  */
- 
+
 package ru.windcorp.progressia.common.hacks;
 
 import java.lang.reflect.Constructor;
@@ -29,15 +29,14 @@ import com.google.common.util.concurrent.MoreExecutors;
 import ru.windcorp.progressia.common.util.crash.CrashReports;
 
 /**
- * This class had to be written because there is not legal way to instantiate a
- * non-async
- * {@link EventBus} with both a custom identifier and a custom exception
- * handler. Which
- * is a shame. Guava maintainers know about the issue but have rejected
- * solutions multiple
- * times <em>without a clearly stated reason</em>; looks like some dirty
- * reflection will
- * have to do.
+ * This class had to be written because there is no legal way to instantiate a
+ * non-async {@link EventBus} with both a custom identifier and a custom
+ * exception handler. Which is a shame. Guava maintainers know about the issue
+ * but have rejected solutions multiple times <em>without a clearly stated
+ * reason</em>; looks like some dirty reflection will have to do.
+ * <p>
+ * When explicitly referencing this class, please mention its usage in
+ * implementation notes because it is unreliable long-term.
  * 
  * @author javapony
  */
diff --git a/src/main/java/ru/windcorp/progressia/common/util/crash/ReportingEventBus.java b/src/main/java/ru/windcorp/progressia/common/util/crash/ReportingEventBus.java
index 141efa9..a95365e 100644
--- a/src/main/java/ru/windcorp/progressia/common/util/crash/ReportingEventBus.java
+++ b/src/main/java/ru/windcorp/progressia/common/util/crash/ReportingEventBus.java
@@ -15,18 +15,34 @@
  * You should have received a copy of the GNU General Public License
  * along with this program.  If not, see <https://www.gnu.org/licenses/>.
  */
- 
+
 package ru.windcorp.progressia.common.util.crash;
 
 import com.google.common.eventbus.EventBus;
 
 import ru.windcorp.progressia.common.hacks.GuavaEventBusHijacker;
 
+/**
+ * A utility for creating Guava's {@link EventBus}es that
+ * {@linkplain CrashReports report} exceptions instead of suppressing them.
+ * 
+ * @author javapony
+ */
 public class ReportingEventBus {
 
 	private ReportingEventBus() {
 	}
 
+	/**
+	 * Instantiates a new {@link EventBus} with the provided identifier that
+	 * reports any unhandled exceptions with {@link CrashReports}.
+	 * 
+	 * @param identifier the identifier of the new bus
+	 * @return the created event bus
+	 * @implNote This implementation relies on {@link GuavaEventBusHijacker} for
+	 *           creating buses with custom identifiers and uncaught exception
+	 *           handlers. It may break suddenly with a Guava update.
+	 */
 	public static EventBus create(String identifier) {
 		return GuavaEventBusHijacker.newEventBus(
 			identifier,