Adds exhaustion to damage sources, cleans up javadocs - Fixes #1592

src/main/java/org/spongepowered/api/event/cause/entity/damage/source/DamageSource.java

@@ -108,24 +108,99 @@ static Builder builder() {
      */
     boolean doesAffectCreative();
 
+    /**
+     * Gets the amount of exhaustion this {@link DamageSource} will
+     * add to the entity, generally only to players.
+     *
+     * <p>In vanilla this is generally set to 0.1 by default and
+     * overridden and set to 0 if the damage is set to be absolute.</p>
+     *
+     * @return The increase in exhaustion
+     */
+    double getExhaustion();
+
     interface Builder extends DamageSourceBuilder<DamageSource, Builder> { }
 
     interface DamageSourceBuilder<T extends DamageSource, B extends DamageSourceBuilder<T, B>> extends ResettableBuilder<T, B> {
 
+        /**
+         * Sets this {@link DamageSource}'s damage to be scaled
+         * by {@link Difficulty}.
+         *
+         * @return This builder
+         */
         B scalesWithDifficulty();
 
+        /**
+         * Sets this {@link DamageSource} as dealing damage that
+         * bypasses armor.
+         *
+         * @return This builder
+         */
         B bypassesArmor();
 
+        /**
+         * Sets whether this {@link DamageSource} as an explosion.
+         *
+         * @return This builder
+         */
         B explosion();
 
+
+        /**
+         * Sets this {@link DamageSource} as not being able to be modified
+         * with damage that is absolute.
+         *
+         * @return This builder
+         */
         B absolute();
 
+        /**
+         * Sets this {@link DamageSource} as considered to be magical
+         * damage. An example is potions.
+         *
+         * @return This builder
+         */
         B magical();
 
+        /**
+         * Sets this {@link DamageSource} as considered to damage creative, or
+         * otherwise "normally unharmable" players.
+         *
+         * @return This builder
+         */
         B creative();
 
+        /**
+         * Sets the amount of exhaustion this {@link DamageSource} will
+         * add to the entity, generally only to players.
+         *
+         * <p>In vanilla this defaults .1 in vanilla, and turns to 0 if the
+         * damage is absolute. This builder generally defaults to it to 0.1
+         * and is not overridden if you set the damage as absolute.</p>
+         *
+         * @param exhaustion The amount of exhaustion to add to the entity
+         * @return This builder
+         */
+        B exhaustion(double exhaustion);
+
+        /**
+         * Sets the {@link DamageType} of this source.
+         *
+         * <p>This is often required to be set.</p>
+         *
+         * @param damageType The desired damage type
+         * @return This builder
+         */
         B type(DamageType damageType);
 
+        /**
+         * Builds an instance of this damage source, based on
+         * the values you inputted into the builder.
+         *
+         * @return The resulting damage source
+         * @throws IllegalStateException If a value required to be set is not set
+         */
         T build() throws IllegalStateException;
 
     }

src/main/java/org/spongepowered/api/event/cause/entity/damage/source/common/AbstractDamageSource.java

@@ -46,6 +46,7 @@ public abstract class AbstractDamageSource implements DamageSource {
     private final boolean explosive;
     private final boolean magic;
     private final boolean creative;
+    private final double exhaustion;
 
     protected AbstractDamageSource(AbstractDamageSourceBuilder<?, ?> builder) {
         this.apiDamageType = checkNotNull(builder.damageType, "DamageType cannot be null!");
@@ -55,6 +56,7 @@ protected AbstractDamageSource(AbstractDamageSourceBuilder<?, ?> builder) {
         this.explosive = builder.explosion;
         this.magic = builder.magical;
         this.creative = builder.creative;
+        this.exhaustion = builder.exhaustion;
     }
 
     @Override
@@ -92,4 +94,9 @@ public boolean doesAffectCreative() {
         return this.creative;
     }
 
+    @Override
+    public double getExhaustion() {
+        return this.exhaustion;
+    }
+
 }

src/main/java/org/spongepowered/api/event/cause/entity/damage/source/common/AbstractDamageSourceBuilder.java

@@ -39,9 +39,9 @@ public abstract class AbstractDamageSourceBuilder<T extends DamageSource, B exte
     protected boolean absolute = false;
     protected boolean magical = false;
     protected boolean creative = false;
+    protected double exhaustion = 0.1;
     protected DamageType damageType = null;
 
-
     @Override
     public B scalesWithDifficulty() {
         this.scales = true;
@@ -78,6 +78,12 @@ public B creative() {
         return (B) this;
     }
 
+    @Override
+    public B exhaustion(double exhaustion) {
+        this.exhaustion = exhaustion;
+        return (B) this;
+    }
+
     @Override
     public B type(DamageType damageType) {
         this.damageType = checkNotNull(damageType, "DamageType cannot be null!");
@@ -93,12 +99,13 @@ public B from(T value) {
         this.explosion = value.isExplosive();
         this.creative = value.doesAffectCreative();
         this.magical = value.isMagic();
+        this.exhaustion = value.getExhaustion();
+        this.damageType = value.getType();
         return (B) this;
     }
 
     @Override
     public B reset() {
-
         return (B) this;
     }
 }

src/main/java/org/spongepowered/api/event/cause/entity/damage/source/common/AbstractEntityDamageSource.java

@@ -39,6 +39,7 @@ public abstract class AbstractEntityDamageSource implements EntityDamageSource {
     private final boolean explosive;
     private final boolean magic;
     private final boolean creative;
+    private final double exhaustion;
     private final Entity source;
 
     protected AbstractEntityDamageSource(AbstractEntityDamageSourceBuilder<?, ?> builder) {
@@ -49,6 +50,7 @@ protected AbstractEntityDamageSource(AbstractEntityDamageSourceBuilder<?, ?> bui
         this.explosive = builder.explosion;
         this.magic = builder.magical;
         this.creative = builder.creative;
+        this.exhaustion = builder.exhaustion;
         this.source = checkNotNull(builder.source, "Entity source cannot be null!");
     }
 
@@ -92,6 +94,11 @@ public boolean doesAffectCreative() {
         return this.creative;
     }
 
+    @Override
+    public double getExhaustion() {
+        return this.exhaustion;
+    }
+
     @SuppressWarnings("unchecked")
     public abstract static class AbstractEntityDamageSourceBuilder<T extends EntityDamageSource,
             B extends EntityDamageSource.EntityDamageSourceBuilder<T, B>>

src/main/java/org/spongepowered/api/event/cause/entity/damage/source/common/AbstractIndirectEntityDamageSource.java

@@ -39,6 +39,7 @@ public abstract class AbstractIndirectEntityDamageSource implements IndirectEnti
     private final boolean explosive;
     private final boolean magic;
     private final boolean creative;
+    private final double exhaustion;
     private final Entity source;
     private final Entity indirect;
 
@@ -50,6 +51,7 @@ protected AbstractIndirectEntityDamageSource(AbstractIndirectEntityDamageSourceB
         this.explosive = builder.explosion;
         this.magic = builder.magical;
         this.creative = builder.creative;
+        this.exhaustion = builder.exhaustion;
         this.source = checkNotNull(builder.sourceEntity, "Entity source cannot be null!");
         this.indirect = checkNotNull(builder.indirect, "Indirect source cannot be null!");
     }
@@ -99,6 +101,11 @@ public Entity getIndirectSource() {
         return this.indirect;
     }
 
+    @Override
+    public double getExhaustion() {
+        return this.exhaustion;
+    }
+
     @SuppressWarnings("unchecked")
     public abstract static class AbstractIndirectEntityDamageSourceBuilder<T extends IndirectEntityDamageSource,
             B extends IndirectEntityDamageSource.AbstractBuilder<T, B>>