Updated documentation for GuavaEventBusHijacker and ReportingEventBus

src/main/java/ru/windcorp/progressia/common/hacks/GuavaEventBusHijacker.java

@@ -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
+ * This class had to be written because there is no legal way to instantiate a
- * non-async
+ * non-async {@link EventBus} with both a custom identifier and a custom
- * {@link EventBus} with both a custom identifier and a custom exception
+ * exception handler. Which is a shame. Guava maintainers know about the issue
- * handler. Which
+ * but have rejected solutions multiple times <em>without a clearly stated
- * is a shame. Guava maintainers know about the issue but have rejected
+ * reason</em>; looks like some dirty reflection will have to do.
- * solutions multiple
+ * <p>
- * times <em>without a clearly stated reason</em>; looks like some dirty
+ * When explicitly referencing this class, please mention its usage in
- * reflection will
+ * implementation notes because it is unreliable long-term.
- * have to do.
  * 
  * @author javapony
  */

src/main/java/ru/windcorp/progressia/common/util/crash/ReportingEventBus.java

@@ -22,11 +22,27 @@ 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,