document event API

common/src/main/java/com/dfsek/terra/api/addons/TerraAddon.java

@@ -6,20 +6,39 @@ import com.dfsek.terra.api.addons.annotations.Author;
 import com.dfsek.terra.api.addons.annotations.Version;
 import org.jetbrains.annotations.NotNull;
 
+/**
+ * Represents an entry point for an addon. Implementations must be annotated with {@link Addon}.
+ */
 public abstract class TerraAddon {
+    /**
+     * Gets the version of this addon.
+     *
+     * @return Addon version.
+     */
     public final @NotNull String getVersion() {
         Version version = getClass().getAnnotation(Version.class);
         return version == null ? "0.1.0" : version.value();
     }
 
+    /**
+     * Gets the author of this addon.
+     *
+     * @return Addon author.
+     */
     public final @NotNull String getAuthor() {
         Author author = getClass().getAnnotation(Author.class);
         return author == null ? "Anon Y. Mous" : author.value();
     }
 
+    /**
+     * Gets the name (ID) of this addon.
+     *
+     * @return Addon ID.
+     */
     public final @NotNull String getName() {
         Addon addon = getClass().getAnnotation(Addon.class);
-        if(addon == null) throw new IllegalStateException("Addon annotation not present"); // This should never happen; the presence of this annotation is checked by the addon loader.
+        if(addon == null)
+            throw new IllegalStateException("Addon annotation not present"); // This should never happen; the presence of this annotation is checked by the addon loader.
         return addon.value();
     }
 

common/src/main/java/com/dfsek/terra/api/event/EventListener.java

@@ -1,4 +1,12 @@
 package com.dfsek.terra.api.event;
 
+import com.dfsek.terra.api.event.events.Event;
+
+/**
+ * Marker interface for a class that contains event listener methods.
+ *
+ * @see Event
+ * @see EventManager
+ */
 public interface EventListener {
 }

common/src/main/java/com/dfsek/terra/api/event/EventManager.java

@@ -3,13 +3,23 @@ package com.dfsek.terra.api.event;
 import com.dfsek.terra.api.addons.TerraAddon;
 import com.dfsek.terra.api.event.events.Event;
 
+/**
+ * Manages event registration and triggering.
+ */
 public interface EventManager {
     /**
      * Call an event, and return the execution status.
+     *
      * @param event Event to pass to all registered EventListeners.
      * @return False if the event is cancellable and has been cancelled, otherwise true.
      */
     boolean callEvent(Event event);
 
+    /**
+     * Register an {@link EventListener} under an {@link TerraAddon}.
+     *
+     * @param addon    Addon to register listener for.
+     * @param listener Listener to register.
+     */
     void registerListener(TerraAddon addon, EventListener listener);
 }

common/src/main/java/com/dfsek/terra/api/event/annotations/Global.java

@@ -1,12 +1,15 @@
 package com.dfsek.terra.api.event.annotations;
 
+import com.dfsek.terra.api.event.events.PackEvent;
+
 import java.lang.annotation.ElementType;
 import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
 /**
- * Specifies that an event handler is to handle all events.
+ * Specifies that an event handler is to handle all {@link PackEvent}s, regardless of whether the pack
+ * depends on the addon's listener.
  */
 @Retention(RetentionPolicy.RUNTIME)
 @Target(ElementType.METHOD)

common/src/main/java/com/dfsek/terra/api/event/events/Cancellable.java

@@ -2,10 +2,21 @@ package com.dfsek.terra.api.event.events;
 
 /**
  * Events that implement this interface may be cancelled.
- *
+ * <p>
  * Cancelling an event is assumed to stop the execution of whatever action triggered the event.
  */
 public interface Cancellable extends Event {
+    /**
+     * Get the cancellation status of the event.
+     *
+     * @return Whether event is cancelled.
+     */
     boolean isCancelled();
-    void setCancelled();
+
+    /**
+     * Set the cancellation status of the event.
+     *
+     * @param cancelled Whether event is cancelled.
+     */
+    void setCancelled(boolean cancelled);
 }

common/src/main/java/com/dfsek/terra/api/event/events/Event.java

@@ -1,4 +1,7 @@
 package com.dfsek.terra.api.event.events;
 
+/**
+ * An event that addons may listen to.
+ */
 public interface Event {
 }

common/src/main/java/com/dfsek/terra/api/event/events/PackEvent.java

@@ -1,8 +1,20 @@
 package com.dfsek.terra.api.event.events;
 
+import com.dfsek.terra.api.event.annotations.Global;
 import com.dfsek.terra.config.pack.ConfigPack;
 
+/**
+ * An event with functionality directly linked to a {@link ConfigPack}.
+ * <p>
+ * PackEvents are only invoked when the pack specifies the addon in its
+ * {@code addon} key (or when the listener is annotated {@link Global}).
+ */
 @SuppressWarnings("InterfaceMayBeAnnotatedFunctional")
 public interface PackEvent extends Event {
+    /**
+     * Get the {@link ConfigPack} associated with this event.
+     *
+     * @return ConfigPack associated with the event.
+     */
     ConfigPack getPack();
 }

common/src/main/java/com/dfsek/terra/api/event/events/config/ConfigPackLoadEvent.java

@@ -3,6 +3,9 @@ package com.dfsek.terra.api.event.events.config;
 import com.dfsek.terra.api.event.events.PackEvent;
 import com.dfsek.terra.config.pack.ConfigPack;
 
+/**
+ * An event related to the loading process of config packs.
+ */
 public abstract class ConfigPackLoadEvent implements PackEvent {
     private final ConfigPack pack;
 

common/src/main/java/com/dfsek/terra/api/injection/Injector.java

@@ -9,18 +9,51 @@ import java.lang.reflect.Modifier;
 import java.util.HashSet;
 import java.util.Set;
 
+/**
+ * Dynamic dependency injector.
+ * <p>
+ * Stores an object to inject, and injects it into objects passed to {@link #inject(Object)}.
+ *
+ * @param <T> Type of object to inject.
+ */
 public class Injector<T> {
     private final T value;
     private final Set<Class<? extends T>> targets = new HashSet<>();
 
+    /**
+     * Instantiate an Injector with a value to inject
+     *
+     * @param value Value to inject
+     */
     public Injector(T value) {
         this.value = value;
     }
 
+    /**
+     * Add an explicit class as a target. Useful for applications where subclasses may cause issues with DI.
+     *
+     * @param target Target class type.
+     */
     public void addExplicitTarget(Class<? extends T> target) {
         targets.add(target);
     }
 
+    /**
+     * Inject the stored object into an object.
+     * <p>
+     * Injects the stored object into any non-static, non-final fields
+     * annotated with {@link Inject},
+     * with type matching the stored object or any explicit targets
+     * ({@link #addExplicitTarget(Class)}.
+     *
+     * @param object Object to inject into
+     * @throws InjectionException If:
+     *                            <ul>
+     *                                <li>Matching field annotated with {@link Inject} is final</li>
+     *                                <li>Matching field annotated with {@link Inject} is static</li>
+     *                                <li>A reflective access exception occurs</li>
+     *                            </ul>
+     */
     public void inject(Object object) throws InjectionException {
         for(Field field : ReflectionUtil.getFields(object.getClass())) {
             Inject inject = field.getAnnotation(Inject.class);

common/src/main/java/com/dfsek/terra/api/injection/exception/InjectionException.java

@@ -1,5 +1,10 @@
 package com.dfsek.terra.api.injection.exception;
 
+import com.dfsek.terra.api.injection.Injector;
+
+/**
+ * Thrown when dynamic dependency injection cannot be completed by an {@link Injector}.
+ */
 public class InjectionException extends Exception {
     private static final long serialVersionUID = -6929631447064215387L;