Improve documentation

src/main/java/net/minestom/server/item/ItemMeta.java

@@ -55,14 +55,17 @@ public class ItemMeta implements Cloneable {
         return builder.build();
     }
 
+    @Contract(pure = true)
     public int getDamage() {
         return damage;
     }
 
+    @Contract(pure = true)
     public boolean isUnbreakable() {
         return unbreakable;
     }
 
+    @Contract(pure = true)
     public int getHideFlag() {
         return hideFlag;
     }

src/main/java/net/minestom/server/item/ItemStack.java

@@ -12,9 +12,18 @@ import java.util.function.Consumer;
 import java.util.function.IntUnaryOperator;
 import java.util.function.UnaryOperator;
 
+/**
+ * Represents an immutable item to be placed inside {@link net.minestom.server.inventory.PlayerInventory},
+ * {@link net.minestom.server.inventory.Inventory} or even on the ground {@link net.minestom.server.entity.ItemEntity}.
+ * <p>
+ * An item stack cannot be null, {@link ItemStack#AIR} should be used instead.
+ */
 public class ItemStack {
 
-    public static final ItemStack AIR = ItemStack.of(Material.AIR);
+    /**
+     * Constant AIR item. Should be used instead of 'null'.
+     */
+    public static final @NotNull ItemStack AIR = ItemStack.of(Material.AIR);
 
     private final UUID uuid = UUID.randomUUID();
     private final StackingRule stackingRule = new VanillaStackingRule(64);
@@ -23,7 +32,7 @@ public class ItemStack {
     private final int amount;
     private final ItemMeta meta;
 
-    protected ItemStack(@NotNull Material material, int amount, ItemMeta meta) {
+    protected ItemStack(@NotNull Material material, int amount, @NotNull ItemMeta meta) {
         this.material = material;
         this.amount = amount;
         this.meta = meta;
@@ -102,7 +111,7 @@ public class ItemStack {
     }
 
     @Contract(pure = true)
-    public @Nullable List<@NotNull Component> getLore() {
+    public @NotNull List<@NotNull Component> getLore() {
         return meta.getLore();
     }
 

src/main/java/net/minestom/server/item/StackingRule.java

@@ -1,5 +1,6 @@
 package net.minestom.server.item;
 
+import org.jetbrains.annotations.Contract;
 import org.jetbrains.annotations.NotNull;
 
 /**
@@ -40,10 +41,10 @@ public abstract class StackingRule {
      *
      * @param item      the {@link ItemStack} to applies the size to
      * @param newAmount the new item size
-     * @return the new {@link ItemStack} with the new amount
+     * @return a new {@link ItemStack item} with the specified amount
      */
-    @NotNull
-    public abstract ItemStack apply(@NotNull ItemStack item, int newAmount);
+    @Contract("_, _ -> new")
+    public abstract @NotNull ItemStack apply(@NotNull ItemStack item, int newAmount);
 
     /**
      * Used to determine the current stack size of an {@link ItemStack}.

src/main/java/net/minestom/server/item/meta/CompassMeta.java

@@ -1,7 +1,5 @@
 package net.minestom.server.item.meta;
 
-import net.kyori.adventure.text.Component;
-import net.minestom.server.item.Enchantment;
 import net.minestom.server.item.ItemMeta;
 import net.minestom.server.item.ItemMetaBuilder;
 import net.minestom.server.utils.Position;
@@ -9,8 +7,6 @@ import org.jetbrains.annotations.NotNull;
 import org.jetbrains.annotations.Nullable;
 import org.jglrxavpok.hephaistos.nbt.NBTCompound;
 
-import java.util.List;
-import java.util.Map;
 import java.util.function.Supplier;
 
 public class CompassMeta extends ItemMeta implements ItemMetaBuilder.Provider<CompassMeta.Builder> {
@@ -20,7 +16,9 @@ public class CompassMeta extends ItemMeta implements ItemMetaBuilder.Provider<Co
     private final Position lodestonePosition;
 
     protected CompassMeta(ItemMetaBuilder metaBuilder,
-                          boolean lodestoneTracked, String lodestoneDimension, Position lodestonePosition) {
+                          boolean lodestoneTracked,
+                          @Nullable String lodestoneDimension,
+                          @Nullable Position lodestonePosition) {
         super(metaBuilder);
         this.lodestoneTracked = lodestoneTracked;
         this.lodestoneDimension = lodestoneDimension;
@@ -31,11 +29,11 @@ public class CompassMeta extends ItemMeta implements ItemMetaBuilder.Provider<Co
         return lodestoneTracked;
     }
 
-    public String getLodestoneDimension() {
+    public @Nullable String getLodestoneDimension() {
         return lodestoneDimension;
     }
 
-    public Position getLodestonePosition() {
+    public @Nullable Position getLodestonePosition() {
         return lodestonePosition;
     }
 
@@ -50,54 +48,16 @@ public class CompassMeta extends ItemMeta implements ItemMetaBuilder.Provider<Co
             return this;
         }
 
-        public Builder lodestoneDimension(String lodestoneDimension) {
+        public Builder lodestoneDimension(@Nullable String lodestoneDimension) {
             this.lodestoneDimension = lodestoneDimension;
             return this;
         }
 
-        public Builder lodestonePosition(Position lodestonePosition) {
+        public Builder lodestonePosition(@Nullable Position lodestonePosition) {
             this.lodestonePosition = lodestonePosition;
             return this;
         }
 
-        @Override
-        public @NotNull Builder displayName(@Nullable Component displayName) {
-            super.displayName(displayName);
-            return this;
-        }
-
-        @Override
-        public @NotNull Builder lore(List<@NotNull Component> lore) {
-            super.lore(lore);
-            return this;
-
-        }
-
-        @Override
-        public @NotNull Builder lore(Component... lore) {
-            super.lore(lore);
-            return this;
-        }
-
-        @Override
-        public @NotNull Builder enchantments(@NotNull Map<Enchantment, Short> enchantments) {
-            super.enchantments(enchantments);
-            return this;
-
-        }
-
-        @Override
-        public @NotNull Builder enchantment(@NotNull Enchantment enchantment, short level) {
-            super.enchantment(enchantment, level);
-            return this;
-        }
-
-        @Override
-        public @NotNull Builder clearEnchantment() {
-            super.clearEnchantment();
-            return this;
-        }
-
         @Override
         public @NotNull CompassMeta build() {
             return new CompassMeta(this, lodestoneTracked, lodestoneDimension, lodestonePosition);

src/test/java/demo/PlayerInit.java

@@ -26,7 +26,6 @@ import net.minestom.server.instance.block.CustomBlock;
 import net.minestom.server.inventory.Inventory;
 import net.minestom.server.inventory.InventoryType;
 import net.minestom.server.inventory.PlayerInventory;
-import net.minestom.server.item.Enchantment;
 import net.minestom.server.item.ItemStack;
 import net.minestom.server.item.Material;
 import net.minestom.server.item.meta.CompassMeta;
@@ -38,7 +37,6 @@ import net.minestom.server.utils.time.TimeUnit;
 import net.minestom.server.world.DimensionType;
 
 import java.util.Collection;
-import java.util.Map;
 import java.util.UUID;
 import java.util.concurrent.ThreadLocalRandom;
 
@@ -68,7 +66,6 @@ public class PlayerInit {
         {
             CompassMeta compassMeta = new CompassMeta.Builder()
                     .lodestonePosition(new Position(0, 0, 0))
-                    .enchantments(Map.of(Enchantment.KNOCKBACK, (short) 5, Enchantment.EFFICIENCY, (short) 10))
                     .build();
 
             ItemStack itemStack = ItemStack.builder(Material.COMPASS)