Add comments to attribute system

src/main/java/net/minestom/server/attribute/Attribute.java

@@ -6,6 +6,9 @@ import java.util.Map;
 import org.jetbrains.annotations.NotNull;
 import org.jetbrains.annotations.Nullable;
 
+/**
+ * Represent a {@link net.minestom.server.entity.LivingEntity living entity} attribute.
+ */
 public class Attribute {
 
 	private static final Map<String, Attribute> ATTRIBUTES = new HashMap<>();
@@ -15,10 +18,28 @@ public class Attribute {
 	private final float maxValue;
 	private final boolean shareWithClient;
 
+	/**
+	 * Create a new attribute with a given key and default.
+	 * <p>
+	 *     By default, this attribute will be sent to the client.
+	 * </p>
+	 *
+	 * @param key the attribute registry key
+	 * @param defaultValue the default value
+	 * @param maxValue the maximum allowed value
+	 */
 	public Attribute(@NotNull String key, float defaultValue, float maxValue) {
 		this(key, true, defaultValue, maxValue);
 	}
 
+	/**
+	 * Create a new attribute with a given key and default.
+	 *
+	 * @param key the attribute registry key
+	 * @param shareWithClient whether to send this attribute to the client
+	 * @param defaultValue the default value
+	 * @param maxValue the maximum allowed value
+	 */
 	public Attribute(@NotNull String key, boolean shareWithClient, float defaultValue, float maxValue) {
 		if (defaultValue > maxValue) {
 			throw new IllegalArgumentException("Default value cannot be greater than the maximum allowed");
@@ -29,39 +50,83 @@ public class Attribute {
 		this.maxValue = maxValue;
 	}
 
+	/**
+	 * Gets the attribute unique key.
+	 *
+	 * @return the attribute key
+	 */
 	@NotNull
 	public String getKey() {
 		return key;
 	}
 
+	/**
+	 * Gets the attribute default value that should be applied.
+	 *
+	 * @return the attribute default value
+	 */
 	public float getDefaultValue() {
 		return defaultValue;
 	}
 
+	/**
+	 * Gets the maximum value applicable to an entity for this attribute.
+	 *
+	 * @return the maximum value of this attribute
+	 */
 	public float getMaxValue() {
 		return maxValue;
 	}
 
+	/**
+	 * Gets whether this attribute's instances should be sent to clients.
+	 *
+	 * @return if this attribute is to be shared
+	 */
 	public boolean isShared() {
 		return shareWithClient;
 	}
 
+	/**
+	 * Register this attribute.
+	 *
+	 * @see #fromKey(String)
+	 * @see #values()
+	 *
+	 * @return this attribute
+	 */
 	@NotNull
 	public Attribute register() {
 		ATTRIBUTES.put(key, this);
 		return this;
 	}
 
+	/**
+	 * Retrieves an attribute by its key.
+	 *
+	 * @param key the key of the attribute
+	 * @return the attribute for the key or null if not any
+	 */
 	@Nullable
 	public static Attribute fromKey(@NotNull String key) {
 		return ATTRIBUTES.get(key);
 	}
 
+	/**
+	 * Retrieves all registered attributes.
+	 *
+	 * @return an array containing all registered attributes
+	 */
 	@NotNull
 	public static Attribute[] values() {
 		return ATTRIBUTES.values().toArray(new Attribute[0]);
 	}
 
+	/**
+	 * Retrieves registered attributes that are shared with the client.
+	 *
+	 * @return an array containing registered, sharable attributes
+	 */
 	@NotNull
 	public static Attribute[] sharedAttributes() {
 		return ATTRIBUTES.values().stream().filter(Attribute::isShared).toArray(Attribute[]::new);

src/main/java/net/minestom/server/attribute/AttributeInstance.java

@@ -9,6 +9,9 @@ import java.util.function.Consumer;
 import org.jetbrains.annotations.NotNull;
 import org.jetbrains.annotations.Nullable;
 
+/**
+ * Represents an instance of an attribute and its modifiers.
+ */
 public class AttributeInstance {
 
 	private final Attribute attribute;
@@ -24,15 +27,31 @@ public class AttributeInstance {
 		this.baseValue = attribute.getDefaultValue();
 	}
 
+	/**
+	 * Gets the attribute associated to this instance.
+	 *
+	 * @return the associated attribute
+	 */
 	@NotNull
 	public Attribute getAttribute() {
 		return attribute;
 	}
 
+	/**
+	 * The base value of this instance without modifiers
+	 *
+	 * @see #setBaseValue(float)
+	 * 
+	 * @return the instance base value
+	 */
 	public float getBaseValue() {
 		return baseValue;
 	}
 
+	/**
+	 * Sets this instance dirty to trigger calculation of the new value.
+	 * Triggers the {@link #propertyChangeListener}.
+	 */
 	private void setDirty() {
 		if (!dirty) {
 			dirty = true;
@@ -42,6 +61,13 @@ public class AttributeInstance {
 		}
 	}
 
+	/**
+	 * Sets the base value of this instance.
+	 * 
+	 * @see #getBaseValue() 
+	 * 
+	 * @param baseValue the new base value
+	 */
 	public void setBaseValue(float baseValue) {
 		if (this.baseValue != baseValue) {
 			this.baseValue = baseValue;
@@ -49,22 +75,42 @@ public class AttributeInstance {
 		}
 	}
 
+	/**
+	 * Add a modifier to this instance.
+	 *
+	 * @param modifier the modifier to add
+	 */
 	public void addModifier(@NotNull AttributeModifier modifier) {
 		if (modifiers.putIfAbsent(modifier.getId(), modifier) == null) {
 			setDirty();
 		}
 	}
 
+	/**
+	 * Remove a modifier from this instance.
+	 *
+	 * @param modifier the modifier to remove
+	 */
 	public void removeModifier(@NotNull AttributeModifier modifier) {
 		if (modifiers.remove(modifier.getId()) != null) {
 			setDirty();
 		}
 	}
 
+	/**
+	 * Get the modifiers applied to this instance.
+	 *
+	 * @return the modifiers.
+	 */
 	public Collection<AttributeModifier> getModifiers() {
 		return modifiers.values();
 	}
 
+	/**
+	 * Gets the value of this instance calculated with modifiers applied.
+	 *
+	 * @return the attribute value
+	 */
 	public float getValue() {
 		if (dirty) {
 			cachedValue = processModifiers();
@@ -73,6 +119,11 @@ public class AttributeInstance {
 		return cachedValue;
 	}
 
+	/**
+	 * Recalculate the value of this attribute instance using the modifiers.
+	 *
+	 * @return the attribute value
+	 */
 	protected float processModifiers() {
 		float base = getBaseValue();
 

src/main/java/net/minestom/server/attribute/AttributeModifier.java

@@ -6,6 +6,9 @@ import io.netty.util.internal.ThreadLocalRandom;
 import net.minestom.server.utils.UniqueIdUtils;
 import org.jetbrains.annotations.NotNull;
 
+/**
+ * Represent an attribute modifier.
+ */
 public class AttributeModifier {
 
 	private final float amount;
@@ -13,10 +16,25 @@ public class AttributeModifier {
 	private final AttributeOperation operation;
 	private final UUID id;
 
+	/**
+	 * Creates a new modifier with a random id.
+	 *
+	 * @param name the name of this modifier
+	 * @param amount the value of this modifier
+	 * @param operation the operation to apply this modifier with
+	 */
 	public AttributeModifier(@NotNull String name, float amount, @NotNull AttributeOperation operation) {
 		this(UniqueIdUtils.createRandomUUID(ThreadLocalRandom.current()), name, amount, operation);
 	}
 
+	/**
+	 * Creates a new modifier.
+	 *
+	 * @param id the id of this modifier
+	 * @param name the name of this modifier
+	 * @param amount the value of this modifier
+	 * @param operation the operation to apply this modifier with
+	 */
 	public AttributeModifier(@NotNull UUID id, @NotNull String name, float amount, @NotNull AttributeOperation operation) {
 		this.id = id;
 		this.name = name;
@@ -24,20 +42,40 @@ public class AttributeModifier {
 		this.operation = operation;
 	}
 
+	/**
+	 * Gets the id of this modifier.
+	 *
+	 * @return the id of this modifier
+	 */
 	@NotNull
 	public UUID getId() {
 		return id;
 	}
 
+	/**
+	 * Gets the name of this modifier.
+	 *
+	 * @return the name of this modifier
+	 */
 	@NotNull
 	public String getName() {
 		return name;
 	}
 
+	/**
+	 * Gets the value of this modifier.
+	 *
+	 * @return the value of this modifier
+	 */
 	public float getAmount() {
 		return amount;
 	}
 
+	/**
+	 * Gets the operation of this modifier.
+	 *
+	 * @return the operation of this modifier
+	 */
 	@NotNull
 	public AttributeOperation getOperation() {
 		return operation;

src/main/java/net/minestom/server/attribute/Attributes.java

@@ -1,5 +1,8 @@
 package net.minestom.server.attribute;
 
+/**
+ * The Minecraft, vanilla, standards attributes.
+ */
 public final class Attributes
 {
     public static final Attribute MAX_HEALTH = (new Attribute("generic.max_health", true, 20, 1024)).register();
@@ -15,4 +18,8 @@ public final class Attributes
     public static final Attribute LUCK = (new Attribute("generic.luck", true, 0, 1024)).register();
     public static final Attribute HORSE_JUMP_STRENGTH = (new Attribute("horse.jump_strength", true, 0.7f, 2)).register();
     public static final Attribute ZOMBIE_SPAWN_REINFORCEMENTS = (new Attribute("zombie.spawn_reinforcements", true, 0, 1)).register();
+
+    private Attributes() throws IllegalAccessException {
+        throw new IllegalAccessException("Cannot instantiate a static class");
+    }
 }

src/main/java/net/minestom/server/entity/LivingEntity.java

@@ -405,6 +405,11 @@ public abstract class LivingEntity extends Entity implements EquipmentHandler {
         return attributeModifiers.get(attribute.getKey());
     }
 
+    /**
+     * Callback used when an attribute instance has been modified.
+     *
+     * @param instance the modified attribute instance
+     */
     protected void onAttributeChanged(@NotNull AttributeInstance instance) { }
 
     /**