Add javadoc to restore events and RestorationAuthoritySystem

src/main/java/org/terasology/logic/health/RestorationAuthoritySystem.java

@@ -28,6 +28,17 @@
 import org.terasology.logic.players.event.OnPlayerRespawnedEvent;
 import org.terasology.math.TeraMath;
 
+/**
+ * This system takes care of restoration of entities with HealthComponent.
+ * To increase the health of an entity, send DoRestoreEvent
+ * <p>
+ * Logic flow for restoration:
+ * - DoRestoreEvent
+ * - BeforeRestoreEvent
+ * - (HealthComponent saved)
+ * - OnRestoredEvent
+ * - OnFullyHealedEvent (if healed to full health)
+ */
 @RegisterSystem(RegisterMode.AUTHORITY)
 public class RestorationAuthoritySystem extends BaseComponentSystem {
 
@@ -39,7 +50,8 @@ public void onRestore(DoRestoreEvent event, EntityRef entity, HealthComponent he
             if (modifiedRestoreAmount > 0) {
                 restore(entity, health, modifiedRestoreAmount);
             } else {
-                entity.send(new DoDamageEvent(-modifiedRestoreAmount));
+                // Cause "healing" damage to entity if modified value of restoration is negative
+                entity.send(new DoDamageEvent(-modifiedRestoreAmount, EngineDamageTypes.HEALING.get()));
             }
         }
     }

src/main/java/org/terasology/logic/health/event/BeforeRestoreEvent.java

@@ -24,24 +24,14 @@
  * Modifications are accumulated as modifiers (additions), multipliers and postModifiers (additions after multipliers).
  */
 public class BeforeRestoreEvent extends AbstractConsumableValueModifiableEvent {
-    /** The entity which is being regenerated. */
+    /** The entity which is being restored. */
     private EntityRef entity;
 
-    /**
-     * Constructor to create a new BeforeRestoreEvent.
-     *
-     * @param amount    The amount by which the entity is restored.
-     * @param entity    The entity which is being restored.
-     */
     public BeforeRestoreEvent(int amount, EntityRef entity) {
         super(amount);
         this.entity = entity;
     }
 
-    /**
-     * Method to get the EntityRef of entity being restored.
-     * @return Entity being restored.
-     */
     public EntityRef getEntity() {
         return entity;
     }

src/main/java/org/terasology/logic/health/event/DoRestoreEvent.java

@@ -15,6 +15,7 @@
  */
 package org.terasology.logic.health.event;
 
+import org.terasology.entitySystem.entity.EntityRef;
 import org.terasology.entitySystem.event.Event;
 
 /**
@@ -23,20 +24,23 @@
 public class DoRestoreEvent implements Event {
     /** The amount of health points being restored. */
     private int amount;
+    /** The entity that caused the restoration */
+    private EntityRef instigator;
 
-    /**
-     * Constructor for event providing amount of restoration.
-     * @param amount    The amount of restoration.
-     */
     public DoRestoreEvent(int amount) {
+        this(amount, EntityRef.NULL);
+    }
+
+    public DoRestoreEvent(int amount, EntityRef entity) {
         this.amount = amount;
+        this.instigator = entity;
     }
 
-    /**
-     * Method to get the amount of restoration.
-     * @return amount of regeneration.
-     */
     public int getAmount() {
         return amount;
     }
+
+    public EntityRef getInstigator() {
+        return instigator;
+    }
 }

src/main/java/org/terasology/logic/health/event/OnRestoredEvent.java

@@ -17,7 +17,13 @@
 
 import org.terasology.entitySystem.entity.EntityRef;
 
+/**
+ * This event is sent after the entity is restored. Final event of restoration logic.
+ */
 public class OnRestoredEvent extends HealthChangedEvent {
+    /**
+     * The amount by which the entity is restored.
+     */
     private int amount;
 
     public OnRestoredEvent(int amount, EntityRef instigator) {