[MCTCommon/Events] Added documentation to event registry

Author: ScribbleTAS

src/main/java/com/minecrafttas/mctcommon/events/EventListenerRegistry.java

@@ -7,8 +7,62 @@
 import java.util.ArrayList;
 import java.util.HashMap;
 
+/**
+ * Registry for making objects available to listen for events.<br>
+ * <br>
+ * Implement an EventInterface into your class, then implement the function.<br>
+ * <br>
+ * In your initializer method, register the instance of the class with {@link EventListenerRegistry#register(EventBase)}
+ * <br>
+ * Example:
+ * <pre>
+ *     public class ClassWithListener implements EventInit {
+ *
+ *          @ Override
+ *          public void onEventInit() {
+ *              // Implement event specific code
+ *          }
+ *     }
+ * </pre>
+ * <br>
+ * To create and fire your own events, check {@link EventBase}<br>
+ */
 public class EventListenerRegistry {
 
+    /**
+     * Base interface for events.<br>
+     * <br>
+     * To create a new event, create an interface and extend EventBase.<br>
+     * Only 1 method is accepted in an event, so it's best to add {@link FunctionalInterface} to the interface.<br>
+     * <br>
+     * Example:
+     * <pre>
+     *     @ FunctionalInterface
+     *     public interface EventInit extends EventBase {
+     *         public void onEventInit();
+     *     }
+     *
+     *     @ FunctionalInterface
+     *     public interface EventAdd extends EventBase {
+     *         public int onEventAdd(int a, int b); // Accepts parameters and return types
+     *     }
+     * </pre>
+     *
+     * To fire your event, use {@link EventListenerRegistry#fireEvent(Class)} with the parameter being the event class.<br>
+     *
+     * <pre>
+     *     EventListenerRegistry.fireEvent(EventInit.class);
+     * </pre>
+     *
+     * To fire an event with parameters and return types:
+     * <pre>
+     *     int eventResult = (int) EventListenerRegistry.fireEvent(EventAdd.class, a, b);
+     * </pre>
+     * When using parameters, the type and the amount of parameters has to match!
+     */
+    public interface EventBase {
+    }
+
     /**
      * Eventlistener Registry.<br>
      * <br>
@@ -20,7 +74,10 @@ public class EventListenerRegistry {
      */
     private static final HashMap<Class<?>, ArrayList<EventBase>> EVENTLISTENER_REGISTRY = new HashMap<>();
 
-
+    /**
+     * Registers an object to be an event listener. The object must implement an event extending {@link EventBase}
+     * @param eventListener The event listener to register
+     */
     public static void register(EventBase eventListener) {
         if (eventListener == null) {
             throw new NullPointerException("Tried to register a packethandler with value null");
@@ -38,6 +95,10 @@ public static void register(EventBase eventListener) {
         }
     }
 
+    /**
+     * Unregisters an object from being an event listener.
+     * @param eventListener The event listener to unregister
+     */
     public static void unregister(EventBase eventListener) {
         if (eventListener == null) {
             throw new NullPointerException("Tried to unregister a packethandler with value null");
@@ -74,17 +135,18 @@ public static Object fireEvent(Class<? extends EventListenerRegistry.EventBase>
      * @return The result of the event, might be null if the event returns nothing
      */
     public static Object fireEvent(Class<? extends EventListenerRegistry.EventBase> eventClass, Object... eventParams) {
-        ArrayList<EventBase> registryList = EVENTLISTENER_REGISTRY.get(eventClass);
-        if (registryList == null) {
+        ArrayList<EventBase> listenerList = EVENTLISTENER_REGISTRY.get(eventClass);
+        if (listenerList == null) {
             throw new EventException("The event has not been registered yet", eventClass);
         }
 
+        //
         EventException toThrow = null;
 
         Method methodToCheck = getEventMethod(eventClass);
 
         Object returnValue = null;
-        for (EventBase eventListener : registryList) {
+        for (EventBase eventListener : listenerList) {
             Method[] methodsInListener = eventListener.getClass().getDeclaredMethods();
 
             for (Method method : methodsInListener) {
@@ -130,14 +192,29 @@ private static Method getEventMethod(Class<? extends EventListenerRegistry.Event
         return test[0];
     }
 
+    /**
+     * @param method The method to check
+     * @param name The name to check
+     * @return If method.getName equals name
+     */
     private static boolean checkName(Method method, String name) {
         return method.getName().equals(name);
     }
 
+    /**
+     * @param method The method to check
+     * @param parameters The list of parameters
+     * @return True, if length of the method parameters is equal to the length of the object parameters
+     */
     private static boolean checkLength(Method method, Object... parameters) {
         return method.getParameterCount() == parameters.length;
     }
 
+    /**
+     * @param method The method to check
+     * @param parameters The list of parameters
+     * @return True, if the types of the parameters equal the object parameters
+     */
     private static boolean checkTypes(Method method, Object... parameters) {
         Class<?>[] methodParameterTypes = ClassUtils.primitivesToWrappers(method.getParameterTypes());
         Class<?>[] eventParameterTypes = getParameterTypes(parameters);
@@ -166,7 +243,4 @@ private static Class<?>[] getParameterTypes(Object... parameters) {
     public static void clear() {
         EVENTLISTENER_REGISTRY.clear();
     }
-
-    public interface EventBase {
-    }
 }