Document attribute modifier listeners and events

litiengine/src/main/java/de/gurkenlabs/litiengine/attributes/Attribute.java

@@ -145,6 +145,10 @@ public void setBaseValue(final T baseValue) {
     this.evaluateValue();
   }
 
+  /**
+   * Evaluates the current value of the attribute by applying all registered modifiers to the base value.
+   * If the new value differs from the previous value, it triggers the value changed event.
+   */
   protected void evaluateValue() {
     final T previousValue = this.value;
     this.value = this.applyModifiers(this.getBase());
@@ -155,10 +159,10 @@ protected void evaluateValue() {
   }
 
   /**
-   * Apply modifiers.
+   * Applies all registered modifiers to the given base value.
    *
-   * @param baseValue the base value
-   * @return the t
+   * @param baseValue The base value to which the modifiers will be applied.
+   * @return The modified value after applying all modifiers.
    */
   protected T applyModifiers(final T baseValue) {
     T currentValue = baseValue;
@@ -169,6 +173,9 @@ protected T applyModifiers(final T baseValue) {
     return currentValue;
   }
 
+  /**
+   * Fires the value changed event to all registered listeners.
+   */
   private void fireValueChangedEvent() {
     for (var listener : this.listeners) {
       listener.valueChanged();

litiengine/src/main/java/de/gurkenlabs/litiengine/attributes/AttributeModifier.java

@@ -7,7 +7,8 @@
 /**
  * An attribute modifier allows to modify attributes by the specified Modification and modify value.
  *
- * @param <T> the generic type
+ * @param <T>
+ *   the generic type
  * @see Attribute#addModifier(AttributeModifier)
  * @see Attribute#modifyBaseValue(AttributeModifier)
  */
@@ -20,8 +21,10 @@ public class AttributeModifier<T extends Number> implements Comparable<Attribute
   /**
    * Initializes a new instance of the {@code AttributeModifier} class.
    *
-   * @param mod         The modification type.
-   * @param modifyValue The modification value to be applied by this instance.
+   * @param mod
+   *   The modification type.
+   * @param modifyValue
+   *   The modification value to be applied by this instance.
    */
   public AttributeModifier(final Modification mod, final double modifyValue) {
     this.modification = mod;
@@ -32,7 +35,8 @@ public AttributeModifier(final Modification mod, final double modifyValue) {
   /**
    * Compares this attribute modifier to another based on the apply order of their modifications.
    *
-   * @param otherModifier The other attribute modifier to compare.
+   * @param otherModifier
+   *   The other attribute modifier to compare.
    * @return An integer representing the comparison result.
    */
   @Override
@@ -43,7 +47,8 @@ public int compareTo(final AttributeModifier<T> otherModifier) {
   /**
    * Checks if this attribute modifier is equal to another object.
    *
-   * @param obj The object to compare with.
+   * @param obj
+   *   The object to compare with.
    * @return True if the objects are equal, false otherwise.
    */
   @Override
@@ -55,10 +60,22 @@ public boolean equals(Object obj) {
     return super.equals(obj);
   }
 
+  /**
+   * Adds a listener that will be notified when the attribute modifier changes.
+   *
+   * @param listener
+   *   The listener to be added.
+   */
   public void onChanged(AttributeModifierListener listener) {
     this.listeners.add(listener);
   }
 
+  /**
+   * Removes a listener so that it will no longer be notified when the attribute modifier changes.
+   *
+   * @param listener
+   *   The listener to be removed.
+   */
   public void removeListener(AttributeModifierListener listener) {
     this.listeners.add(listener);
   }
@@ -93,7 +110,8 @@ public boolean isActive() {
   /**
    * Modifies the provided value based on the modification type and modify value of this attribute modifier.
    *
-   * @param modvalue The original value to be modified.
+   * @param modvalue
+   *   The original value to be modified.
    * @return The modified value.
    */
   public T modify(final T modvalue) {
@@ -114,7 +132,8 @@ public T modify(final T modvalue) {
   /**
    * Sets the modify value for this attribute modifier.
    *
-   * @param value The new modify value.
+   * @param value
+   *   The new modify value.
    */
   public void setModifyValue(double value) {
     var previous = this.modifyValue;
@@ -128,7 +147,8 @@ public void setModifyValue(double value) {
   /**
    * Sets the active status of this attribute modifier.
    *
-   * @param active True to activate, false to deactivate.
+   * @param active
+   *   True to activate, false to deactivate.
    */
   public void setActive(boolean active) {
     var previous = this.active;

litiengine/src/main/java/de/gurkenlabs/litiengine/attributes/AttributeModifierListener.java

@@ -2,7 +2,14 @@
 
 import java.util.EventListener;
 
+/**
+ * An interface for listening to changes in attribute modifiers. Classes that implement this interface can be used to handle events when an attribute
+ * modifier changes.
+ */
 @FunctionalInterface
 public interface AttributeModifierListener extends EventListener {
+  /**
+   * This method is called when an attribute modifier changes.
+   */
   void modifierChanged();
 }

litiengine/src/main/java/de/gurkenlabs/litiengine/attributes/AttributeValueListener.java

@@ -2,7 +2,18 @@
 
 import java.util.EventListener;
 
+/**
+ * A listener interface for receiving attribute value change events.
+ * The class that is interested in processing an attribute value change event
+ * implements this interface, and the object created with that class is registered
+ * with a component using the component's `addAttributeValueListener` method.
+ * When the attribute value change event occurs, that object's `valueChanged` method
+ * is invoked.
+ */
 @FunctionalInterface
 public interface AttributeValueListener extends EventListener {
+  /**
+   * Invoked when the value of an attribute has changed.
+   */
   void valueChanged();
 }

litiengine/src/main/java/de/gurkenlabs/litiengine/attributes/RangeAttribute.java

@@ -4,6 +4,13 @@
 import java.util.List;
 import java.util.concurrent.CopyOnWriteArrayList;
 
+/**
+ * Represents an attribute with a range of values, including minimum and maximum values. This class extends the {@code Attribute} class and provides
+ * additional functionality for handling minimum and maximum value modifiers.
+ *
+ * @param <T>
+ *   The type of the attribute value, which must extend {@code Number}.
+ */
 public class RangeAttribute<T extends Number> extends Attribute<T> {
   private final List<AttributeModifier<T>> minModifiers;
   private final List<AttributeModifier<T>> maxModifiers;
@@ -16,11 +23,11 @@ public class RangeAttribute<T extends Number> extends Attribute<T> {
    * Initializes a new instance of the {@code RangeAttribute} class.
    *
    * @param maxValue
-   *          The max value of this attribute.
+   *   The max value of this attribute.
    * @param minValue
-   *          The min value of this attribute
+   *   The min value of this attribute
    * @param baseValue
-   *          The base (initial) value of this attribute
+   *   The base (initial) value of this attribute
    */
   public RangeAttribute(final T maxValue, final T minValue, final T baseValue) {
     super(baseValue);
@@ -32,6 +39,13 @@ public RangeAttribute(final T maxValue, final T minValue, final T baseValue) {
     this.evaluateValue();
   }
 
+  /**
+   * Adds a modifier to the minimum value of the attribute. If the modifier is already present, it does nothing. After adding the modifier, it sorts
+   * the modifiers and re-evaluates the attribute value.
+   *
+   * @param modifier
+   *   The modifier to be added.
+   */
   public void addMinModifier(final AttributeModifier<T> modifier) {
     if (this.getMinModifiers().contains(modifier)) {
       return;
@@ -42,6 +56,13 @@ public void addMinModifier(final AttributeModifier<T> modifier) {
     this.evaluateValue();
   }
 
+  /**
+   * Adds a modifier to the maximum value of the attribute. If the modifier is already present, it does nothing. After adding the modifier, it sorts
+   * the modifiers and re-evaluates the attribute value.
+   *
+   * @param modifier
+   *   The modifier to be added.
+   */
   public void addMaxModifier(final AttributeModifier<T> modifier) {
     if (this.getMaxModifiers().contains(modifier)) {
       return;
@@ -52,60 +73,128 @@ public void addMaxModifier(final AttributeModifier<T> modifier) {
     this.evaluateValue();
   }
 
+  /**
+   * Gets the current value of the attribute, ensuring it is within the defined range.
+   *
+   * @return The current value of the attribute.
+   */
   @Override
   public T get() {
     return this.valueInRange(super.get());
   }
 
+  /**
+   * Gets the minimum value of the attribute after applying all modifiers.
+   *
+   * @return The minimum value of the attribute.
+   */
   public T getMin() {
     return this.minValue;
   }
 
+  /**
+   * Gets the maximum value of the attribute after applying all modifiers.
+   *
+   * @return The maximum value of the attribute.
+   */
   public T getMax() {
     return this.maxValue;
   }
 
+  /**
+   * Gets the relative current value of the attribute as a float. This is calculated as the current value divided by the maximum value.
+   *
+   * @return The relative current value of the attribute.
+   */
   public float getRelativeCurrentValue() {
     return this.get().floatValue() / this.getMax().floatValue();
   }
 
+  /**
+   * Modifies the base value of the attribute using the provided modifier. Ensures the new base value is within the defined range and re-evaluates the
+   * attribute value.
+   *
+   * @param modifier
+   *   The modifier to be applied to the base value.
+   */
   @Override
   public void modifyBaseValue(final AttributeModifier<T> modifier) {
     this.setBaseValue(this.valueInRange(modifier.modify(this.getBase())));
     this.evaluateValue();
   }
 
+  /**
+   * Modifies the maximum base value of the attribute using the provided modifier. Re-evaluates the attribute value after modification.
+   *
+   * @param modifier
+   *   The modifier to be applied to the maximum base value.
+   */
   public void modifyMaxBaseValue(final AttributeModifier<T> modifier) {
     this.maxBaseValue = modifier.modify(this.maxBaseValue);
     this.evaluateValue();
   }
 
+  /**
+   * Sets the base value of the attribute to the minimum value.
+   */
   public void setToMin() {
     this.setBaseValue(this.getMin());
   }
 
+  /**
+   * Sets the base value of the attribute to the maximum value.
+   */
   public void setToMax() {
     this.setBaseValue(this.getMax());
   }
 
+  /**
+   * Sets the maximum base value of the attribute. Re-evaluates the attribute value after setting the new maximum base value.
+   *
+   * @param maxValue
+   *   The new maximum base value to be set.
+   */
   public void setMaxBaseValue(final T maxValue) {
     this.maxBaseValue = maxValue;
     this.evaluateValue();
   }
 
+  /**
+   * Sets the minimum base value of the attribute. Re-evaluates the attribute value after setting the new minimum base value.
+   *
+   * @param minValue
+   *   The new minimum base value to be set.
+   */
   public void setMinBaseValue(final T minValue) {
     this.minBaseValue = minValue;
     this.evaluateValue();
   }
 
+  /**
+   * Gets the list of modifiers applied to the minimum value of the attribute.
+   *
+   * @return The list of minimum value modifiers.
+   */
   protected List<AttributeModifier<T>> getMinModifiers() {
     return this.minModifiers;
   }
 
+  /**
+   * Gets the list of modifiers applied to the maximum value of the attribute.
+   *
+   * @return The list of maximum value modifiers.
+   */
   protected List<AttributeModifier<T>> getMaxModifiers() {
     return this.maxModifiers;
   }
 
+  /**
+   * Applies all minimum value modifiers to the given value.
+   *
+   * @param maxValue
+   *   The value to which the minimum value modifiers will be applied.
+   * @return The modified value after applying all minimum value modifiers.
+   */
   protected T applyMinModifiers(final T maxValue) {
     T currentValue = maxValue;
     for (final AttributeModifier<T> modifier : this.getMinModifiers()) {
@@ -115,6 +204,13 @@ protected T applyMinModifiers(final T maxValue) {
     return currentValue;
   }
 
+  /**
+   * Applies all maximum value modifiers to the given value.
+   *
+   * @param maxValue
+   *   The value to which the maximum value modifiers will be applied.
+   * @return The modified value after applying all maximum value modifiers.
+   */
   protected T applyMaxModifiers(final T maxValue) {
     T currentValue = maxValue;
     for (final AttributeModifier<T> modifier : this.getMaxModifiers()) {
@@ -124,13 +220,24 @@ protected T applyMaxModifiers(final T maxValue) {
     return currentValue;
   }
 
+  /**
+   * Evaluates the current value of the attribute by applying all registered modifiers to the base, minimum, and maximum values. Ensures the attribute
+   * value is within the defined range.
+   */
   @Override
   protected void evaluateValue() {
     super.evaluateValue();
     this.minValue = this.applyMinModifiers(this.minBaseValue);
     this.maxValue = this.applyMaxModifiers(this.maxBaseValue);
   }
 
+  /**
+   * Ensures the given value is within the defined range of minimum and maximum values.
+   *
+   * @param value
+   *   The value to be checked.
+   * @return The value if it is within the range, otherwise the nearest boundary value.
+   */
   private T valueInRange(final T value) {
     if (value.doubleValue() < this.getMin().doubleValue()) {
       return this.getMin();