Comments

src/main/java/net/minestom/server/chat/ChatParser.java

@@ -9,7 +9,7 @@ import com.google.gson.JsonParser;
 /**
  * Class used to convert JSON string to proper chat message representation
  */
-public class ChatParser {
+public final class ChatParser {
 
     public static final char COLOR_CHAR = (char) 0xA7; // Represent the character '§'
 

src/main/java/net/minestom/server/command/CommandManager.java

@@ -26,7 +26,12 @@ import org.apache.commons.lang3.tuple.Pair;
 import java.util.*;
 import java.util.function.Consumer;
 
-public class CommandManager {
+/**
+ * Manager used to register {@link Command} and {@link CommandProcessor}.
+ * <p>
+ * It is also possible to simulate a command using {@link #execute(CommandSender, String)}.
+ */
+public final class CommandManager {
 
     public static final String COMMAND_PREFIX = "/";
 
@@ -66,7 +71,7 @@ public class CommandManager {
     }
 
     /**
-     * Register a command with all the auto-completion features
+     * Register a {@link Command}
      *
      * @param command the command to register
      */
@@ -75,7 +80,7 @@ public class CommandManager {
     }
 
     /**
-     * Get the command register by {@link #register(Command)}
+     * Get the {@link Command} registered by {@link #register(Command)}
      *
      * @param commandName the command name
      * @return the command associated with the name, null if not any
@@ -85,7 +90,7 @@ public class CommandManager {
     }
 
     /**
-     * Register a simple command without auto-completion
+     * Register a {@link CommandProcessor}
      *
      * @param commandProcessor the command to register
      */
@@ -101,7 +106,7 @@ public class CommandManager {
     }
 
     /**
-     * Get the command register by {@link #register(CommandProcessor)}
+     * Get the {@link CommandProcessor} registered by {@link #register(CommandProcessor)}
      *
      * @param commandName the command name
      * @return the command associated with the name, null if not any
@@ -111,7 +116,7 @@ public class CommandManager {
     }
 
     /**
-     * Execute a command for a sender
+     * Execute a command for a {@link ConsoleSender}
      *
      * @param sender  the sender of the command
      * @param command the raw command string (without the command prefix)
@@ -154,16 +159,16 @@ public class CommandManager {
     }
 
     /**
-     * Get the console sender (which is used as a {@link CommandSender})
+     * Get the {@link ConsoleSender} (which is used as a {@link CommandSender})
      *
-     * @return the console sender
+     * @return the {@link ConsoleSender}
      */
     public ConsoleSender getConsoleSender() {
         return consoleSender;
     }
 
     /**
-     * Get the declare commands packet for a specific player
+     * Get the {@link DeclareCommandsPacket} for a specific player
      * <p>
      * Can be used to update the player auto-completion list
      *

src/main/java/net/minestom/server/command/CommandSender.java

@@ -33,55 +33,59 @@ public interface CommandSender {
     /**
      * Return all permissions associated to this command sender.
      * The returned collection should be modified only by subclasses
-     * @return
+     *
+     * @return the permissions of this command sender.
      */
     Collection<Permission> getAllPermissions();
 
     /**
-     * Adds a permission to this commandSender
-     * @param permission
+     * Adds a {@link Permission} to this commandSender
+     *
+     * @param permission the permission to add
      */
     default void addPermission(Permission permission) {
         getAllPermissions().add(permission);
     }
 
     /**
-     * Removes a permission from this commandSender
-     * @param permission
+     * Removes a {@link Permission} from this commandSender
+     *
+     * @param permission the permission to remove
      */
     default void removePermission(Permission permission) {
         getAllPermissions().remove(permission);
     }
 
     /**
-     * Checks if the given permission is possessed by this command sender.
+     * Checks if the given {@link Permission} is possessed by this command sender.
      * Simple shortcut to <pre>getAllPermissions().contains(permission) &amp;&amp; permission.isValidFor(this)</pre> for readability.
+     *
      * @param p permission to check against
-     * @return
+     * @return true if the sender has the permission and validate {@link Permission#isValidFor(CommandSender)}
      */
     default boolean hasPermission(Permission p) {
         return getAllPermissions().contains(p) && p.isValidFor(this);
     }
 
     /**
-     * Checks if the given permission is possessed by this command sender.
-     * Will call {@link Permission#isValidFor(CommandSender)} on all permissions that are an instance of permissionClass.
+     * Checks if the given {@link Permission} is possessed by this command sender.
+     * Will call {@link Permission#isValidFor(CommandSender)} on all permissions that are an instance of {@code permissionClass}.
      * If no matching permission is found, this result returns false.
      *
-     * @param permissionClass
+     * @param permissionClass the permission class to check
+     * @return true if the sender has the permission and validate {@link Permission#isValidFor(CommandSender)}
      * @see #getAllPermissions()
-     * @return
      */
     default boolean hasPermission(Class<? extends Permission> permissionClass) {
         boolean result = true;
         boolean foundPerm = false;
-        for(Permission p : getAllPermissions()) {
-            if(permissionClass.isInstance(p)) {
+        for (Permission p : getAllPermissions()) {
+            if (permissionClass.isInstance(p)) {
                 foundPerm = true;
                 result &= p.isValidFor(this);
             }
         }
-        if(!foundPerm)
+        if (!foundPerm)
             return false;
         return result;
     }
@@ -105,20 +109,22 @@ public interface CommandSender {
     }
 
     /**
-     * Casts this object to a Player
+     * Casts this object to a {@link Player}
      * No checks are performed, {@link ClassCastException} can very much happen
+     *
      * @see #isPlayer()
      */
     default Player asPlayer() {
-        return (Player)this;
+        return (Player) this;
     }
 
     /**
-     * Casts this object to a ConsoleSender
+     * Casts this object to a {@link ConsoleSender}
      * No checks are performed, {@link ClassCastException} can very much happen
+     *
      * @see #isConsole()
      */
     default ConsoleSender asConsole() {
-        return (ConsoleSender)this;
+        return (ConsoleSender) this;
     }
 }

src/main/java/net/minestom/server/command/builder/ArgumentCallback.java

@@ -6,6 +6,7 @@ import net.minestom.server.command.builder.arguments.Argument;
 /**
  * Callback executed when an error is found within the {@link Argument}
  */
+@FunctionalInterface
 public interface ArgumentCallback {
 
     /**

src/main/java/net/minestom/server/command/builder/Command.java

@@ -33,12 +33,13 @@ import java.util.List;
  */
 public class Command {
 
-    private String name;
-    private String[] aliases;
+    private final String name;
+    private final String[] aliases;
 
     private CommandExecutor defaultExecutor;
     private CommandCondition condition;
-    private List<CommandSyntax> syntaxes;
+
+    private final List<CommandSyntax> syntaxes;
 
     /**
      * Create a {@link Command} with a name and one or multiple aliases
@@ -93,7 +94,7 @@ public class Command {
      * @param callback the callback for the argument
      * @param argument the argument which get the callback
      */
-    public void setArgumentCallback(ArgumentCallback callback, Argument argument) {
+    public void setArgumentCallback(ArgumentCallback callback, Argument<?> argument) {
         argument.setCallback(callback);
     }
 
@@ -105,7 +106,7 @@ public class Command {
      * @param executor the executor to call when the syntax is successfully received
      * @param args     all the arguments of the syntax
      */
-    public void addSyntax(CommandExecutor executor, Argument... args) {
+    public void addSyntax(CommandExecutor executor, Argument<?>... args) {
         CommandSyntax syntax = new CommandSyntax(args);
         syntax.setExecutor(executor);
         this.syntaxes.add(syntax);
@@ -163,7 +164,7 @@ public class Command {
      * Allow for tab auto completion, this is called everytime the player press a key in the chat
      * when in a dynamic argument ({@link ArgumentDynamicWord} and {@link ArgumentDynamicStringArray})
      *
-     * @param text the whole player text
+     * @param text the whole player's text
      * @return the array containing all the suggestion for the current arg (split " ")
      */
     public String[] onDynamicWrite(String text) {

src/main/java/net/minestom/server/command/builder/CommandExecutor.java

@@ -2,6 +2,7 @@ package net.minestom.server.command.builder;
 
 import net.minestom.server.command.CommandSender;
 
+@FunctionalInterface
 public interface CommandExecutor {
     void apply(CommandSender source, Arguments args);
 }

src/main/java/net/minestom/server/event/CancellableEvent.java

@@ -1,25 +1,25 @@
 package net.minestom.server.event;
 
 /**
- * Represent an event which can be cancelled
+ * Represent an {@link Event} which can be cancelled
  */
 public class CancellableEvent extends Event {
 
     private boolean cancelled;
 
     /**
-     * Get if the event will be cancelled or not
+     * Get if the {@link Event} should be cancelled or not
      *
-     * @return true if the event should be cancelled, false otherwise
+     * @return true if the {@link Event} should be cancelled
      */
     public boolean isCancelled() {
         return cancelled;
     }
 
     /**
-     * Mark the event as cancelled or not
+     * Mark the {@link Event} as cancelled or not
      *
-     * @param cancel true if the event should be cancelled, false otherwise
+     * @param cancel true if the {@link Event} should be cancelled, false otherwise
      */
     public void setCancelled(boolean cancel) {
         this.cancelled = cancel;

src/main/java/net/minestom/server/event/Event.java

@@ -1,5 +1,9 @@
 package net.minestom.server.event;
 
-public class Event {
+import net.minestom.server.event.handler.EventHandler;
 
+/**
+ * Object which can be listened to by an {@link EventHandler}
+ */
+public class Event {
 }

src/main/java/net/minestom/server/event/handler/EventHandler.java

@@ -87,7 +87,7 @@ public interface EventHandler {
     }
 
     /**
-     * Call a {@link CancellableEvent} and execute {@code successCallback} if the event is not cancelled
+     * Call a {@link CancellableEvent} and execute {@code successCallback} if the {@link Event} is not cancelled
      * <p>
      * Does call {@link #callEvent(Class, Event)} internally
      *

src/main/java/net/minestom/server/instance/Chunk.java

@@ -38,6 +38,9 @@ import java.util.function.Consumer;
  * A chunk is a part of an {@link Instance}, limited by a size of 16x256x16 blocks and subdivided in 16 sections of 16 blocks height.
  * Should contains all the blocks located at those positions and manage their tick updates.
  * <p>
+ * Chunks can be serialized using {@link #getSerializedData()} and deserialized back with {@link #readChunk(BinaryReader, ChunkCallback)},
+ * allowing you to implement your own storage solution if needed.
+ * <p>
  * You can create your own implementation of this class by extending it and create the objects in {@link InstanceContainer#setChunkSupplier(ChunkSupplier)}.
  */
 public abstract class Chunk implements Viewable, DataContainer {

src/main/java/net/minestom/server/instance/DynamicChunk.java

@@ -26,6 +26,9 @@ import java.util.HashSet;
 import java.util.Set;
 import java.util.concurrent.CopyOnWriteArraySet;
 
+/**
+ * Represents a {@link Chunk} which store each individual block in memory.
+ */
 public class DynamicChunk extends Chunk {
 
     // blocks id based on coordinate, see Chunk#getBlockIndex

src/main/java/net/minestom/server/instance/InstanceManager.java

@@ -10,7 +10,7 @@ import java.util.UUID;
 import java.util.concurrent.CopyOnWriteArraySet;
 
 /**
- * Used to register instances
+ * Used to register {@link Instance}
  */
 public final class InstanceManager {
 

src/main/java/net/minestom/server/instance/StaticChunk.java

@@ -12,6 +12,14 @@ import net.minestom.server.world.biomes.Biome;
 import java.util.HashSet;
 import java.util.Set;
 
+/**
+ * Represents a {@link Chunk} which does not store any block, it makes use of a {@link BlockProvider}
+ * instead to use less memory.
+ * <p>
+ * Can be used for very simple chunks such as flat or others with not any random factor.
+ * <p>
+ * WARNING: adding blocks or anything to this chunk would not work, it is static.
+ */
 public class StaticChunk extends Chunk {
 
     protected final BlockProvider blockProvider;

src/main/java/net/minestom/server/instance/WorldBorder.java

@@ -7,7 +7,7 @@ import net.minestom.server.network.packet.server.play.WorldBorderPacket;
 import net.minestom.server.utils.Position;
 
 /**
- * Represent the world border of an instance
+ * Represent the world border of an {@link Instance}
  */
 public class WorldBorder {
 

src/main/java/net/minestom/server/inventory/EquipmentHandler.java

@@ -11,43 +11,43 @@ import java.util.ArrayList;
 import java.util.List;
 
 /**
- * Represent an entity which can have item in hand and armor slots
+ * Represent an {@link Entity} which can have {@link ItemStack} in hands and armor slots
  */
 public interface EquipmentHandler {
 
     /**
-     * Get the item in main hand
+     * Get the {@link ItemStack} in main hand
      *
-     * @return the item in main hand
+     * @return the {@link ItemStack} in main hand
      */
     ItemStack getItemInMainHand();
 
     /**
-     * Change the main hand item
+     * Change the main hand {@link ItemStack}
      *
-     * @param itemStack the main hand item
+     * @param itemStack the main hand {@link ItemStack}
      */
     void setItemInMainHand(ItemStack itemStack);
 
     /**
-     * Get the item in off hand
+     * Get the {@link ItemStack} in off hand
      *
      * @return the item in off hand
      */
     ItemStack getItemInOffHand();
 
     /**
-     * Change the off hand item
+     * Change the off hand {@link ItemStack}
      *
-     * @param itemStack the off hand item
+     * @param itemStack the off hand {@link ItemStack}
      */
     void setItemInOffHand(ItemStack itemStack);
 
     /**
-     * Get the item in the specific hand
+     * Get the {@link ItemStack} in the specific hand
      *
-     * @param hand the hand to get the item from
-     * @return the item in {@code hand}
+     * @param hand the hand to get the {@link ItemStack} from
+     * @return the {@link ItemStack} in {@code hand}
      */
     default ItemStack getItemInHand(Player.Hand hand) {
         switch (hand) {
@@ -63,10 +63,10 @@ public interface EquipmentHandler {
     }
 
     /**
-     * Change the item in the specific hand
+     * Change the {@link ItemStack} in the specific hand
      *
      * @param hand  the hand to set the item to
-     * @param stack the itemstack to set
+     * @param stack the {@link ItemStack} to set
      */
     default void setItemInHand(Player.Hand hand, ItemStack stack) {
         switch (hand) {
@@ -140,7 +140,7 @@ public interface EquipmentHandler {
      * Get the equipment in a specific slot
      *
      * @param slot the equipment to get the item from
-     * @return the equipment item
+     * @return the equipment {@link ItemStack}
      */
     default ItemStack getEquipment(EntityEquipmentPacket.Slot slot) {
         switch (slot) {

src/main/java/net/minestom/server/inventory/InventoryModifier.java

@@ -11,7 +11,7 @@ import java.util.List;
 public interface InventoryModifier {
 
     /**
-     * Set an item at the specified slot
+     * Set an {@link ItemStack} at the specified slot
      *
      * @param slot      the slot to set the item
      * @param itemStack the item to set
@@ -19,7 +19,7 @@ public interface InventoryModifier {
     void setItemStack(int slot, ItemStack itemStack);
 
     /**
-     * Add an item to the inventory
+     * Add an {@link ItemStack} to the inventory
      *
      * @param itemStack the item to add
      * @return true if the item has been sucessfully fully added, false otherwise
@@ -32,7 +32,7 @@ public interface InventoryModifier {
     void clear();
 
     /**
-     * Get the item at the specified slot
+     * Get the {@link ItemStack} at the specified slot
      *
      * @param slot the slot to check
      * @return the item in the slot {@code slot}
@@ -40,7 +40,7 @@ public interface InventoryModifier {
     ItemStack getItemStack(int slot);
 
     /**
-     * Get all the items in the inventory
+     * Get all the {@link ItemStack} in the inventory
      *
      * @return an array containing all the inventory's items
      */
@@ -54,14 +54,14 @@ public interface InventoryModifier {
     int getSize();
 
     /**
-     * Get all the inventory conditions of this inventory
+     * Get all the {@link InventoryCondition} of this inventory
      *
      * @return the inventory conditions
      */
     List<InventoryCondition> getInventoryConditions();
 
     /**
-     * Add a new inventory condition to this inventory
+     * Add a new {@link InventoryCondition} to this inventory
      *
      * @param inventoryCondition the inventory condition to add
      */

src/main/java/net/minestom/server/inventory/PlayerInventory.java

@@ -26,6 +26,9 @@ import java.util.concurrent.CopyOnWriteArrayList;
 
 import static net.minestom.server.utils.inventory.PlayerInventoryUtils.*;
 
+/**
+ * Represents the inventory of a {@link Player}
+ */
 public class PlayerInventory implements InventoryModifier, InventoryClickHandler, EquipmentHandler {
 
     public static final int INVENTORY_SIZE = 46;

src/main/java/net/minestom/server/inventory/condition/InventoryCondition.java

@@ -1,10 +1,22 @@
 package net.minestom.server.inventory.condition;
 
 import net.minestom.server.entity.Player;
+import net.minestom.server.inventory.InventoryModifier;
 import net.minestom.server.inventory.click.ClickType;
 
+/**
+ * Can be added to any {@link InventoryModifier} in order to listen to any issued clicks.
+ */
+@FunctionalInterface
 public interface InventoryCondition {
 
+    /**
+     * Called when a {@link Player} clicks in the inventory where this {@link InventoryCondition} has been added to.
+     *
+     * @param player                   the player who clicked in the inventory
+     * @param slot                     the slot clicked
+     * @param clickType                the click type
+     * @param inventoryConditionResult the result of this callback
+     */
     void accept(Player player, int slot, ClickType clickType, InventoryConditionResult inventoryConditionResult);
-
 }

src/main/java/net/minestom/server/inventory/condition/InventoryConditionResult.java

@@ -2,6 +2,9 @@ package net.minestom.server.inventory.condition;
 
 import net.minestom.server.item.ItemStack;
 
+/**
+ * Used by {@link InventoryCondition} to step in inventory click processing.
+ */
 public class InventoryConditionResult {
 
     private ItemStack clickedItem, cursorItem;

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

@@ -1,5 +1,8 @@
 package net.minestom.server.item;
 
+/**
+ * Represents a flag which can be applied to an {@link ItemStack} using {@link ItemStack#addItemFlags(ItemFlag...)}.
+ */
 public enum ItemFlag {
     HIDE_ENCHANTS(1),
     HIDE_ATTRIBUTES(2),
@@ -9,6 +12,7 @@ public enum ItemFlag {
     HIDE_POTION_EFFECTS(32);
 
     private final int bitFieldPart;
+
     ItemFlag(int bit) {
         this.bitFieldPart = bit;
     }

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

@@ -1,8 +1,8 @@
 package net.minestom.server.item;
 
 /**
- * Represent the stacking rule of an item
- * This can be used to mimic the vanilla one (using the item amount displayed)
+ * Represent the stacking rule of an {@link ItemStack}
+ * This can be used to mimic the vanilla one (using the displayed item quantity)
  * or a complete new one which can be stored in lore, name, etc...
  */
 public abstract class StackingRule {
@@ -14,39 +14,40 @@ public abstract class StackingRule {
     }
 
     /**
-     * Used to know if two ItemStack can be stacked together
+     * Used to know if two {@link ItemStack} can be stacked together
      *
-     * @param item1 the first item
-     * @param item2 the second item
-     * @return true if both item can be stacked together (do not take their amount in consideration)
+     * @param item1 the first {@link ItemStack}
+     * @param item2 the second {@link ItemStack}
+     * @return true if both {@link ItemStack} can be stacked together
+     * (without taking their amount in consideration)
      */
     public abstract boolean canBeStacked(ItemStack item1, ItemStack item2);
 
     /**
-     * Used to know if an ItemStack can have the size {@code newAmount} applied
+     * Used to know if an {@link ItemStack} can have the size {@code newAmount} applied
      *
-     * @param item      the item to check
+     * @param item      the {@link ItemStack} to check
      * @param newAmount the desired new amount
-     * @return true if item can have its stack size set to newAmount
+     * @return true if {@code item} can have its stack size set to newAmount
      */
     public abstract boolean canApply(ItemStack item, int newAmount);
 
     /**
-     * Change the size of the item to {@code newAmount}
+     * Change the size of the {@link ItemStack} to {@code newAmount}
      * At this point we know that the item can have this stack size applied
      *
-     * @param item      the item stack to applies the size to
+     * @param item      the {@link ItemStack} to applies the size to
      * @param newAmount the new item size
-     * @return the new ItemStack with the new amount
+     * @return the new {@link ItemStack} with the new amount
      */
     public abstract ItemStack apply(ItemStack item, int newAmount);
 
     /**
-     * Used to determine the current stack size of an item
-     * It is possible to have it stored in its Data object, lore, etc...
+     * Used to determine the current stack size of an {@link ItemStack}
+     * It is possible to have it stored in its {@link net.minestom.server.data.Data} object, lore, etc...
      *
-     * @param itemStack the item stack to check the size
-     * @return the correct size of itemStack
+     * @param itemStack the {@link ItemStack} to check the size
+     * @return the correct size of {@link ItemStack}
      */
     public abstract int getAmount(ItemStack itemStack);
 

src/main/java/net/minestom/server/permission/Permission.java

@@ -6,13 +6,16 @@ import org.jetbrains.annotations.NotNull;
 import org.jetbrains.annotations.Nullable;
 
 /**
- * Representation of a permission granted to a CommandSender
+ * Representation of a permission granted to a {@link CommandSender}
  */
 @FunctionalInterface
 public interface Permission {
 
     /**
-     * Does the given commandSender have the permission represented by this object?
+     * Does the given {@link CommandSender} have the permission represented by this object?
+     * <p>
+     * Called with {@link CommandSender#hasPermission(Permission)}, the {@link CommandSender} requires to both
+     * have this permission and validate the condition in this method.
      *
      * @param commandSender the command sender
      * @return true if the commandSender possesses this permission
@@ -22,7 +25,7 @@ public interface Permission {
     /**
      * Writes any required data for this permission inside the given destination
      *
-     * @param destination Data to write to
+     * @param destination {@link Data} to write to
      */
     default void write(@NotNull Data destination) {
     }
@@ -30,7 +33,7 @@ public interface Permission {
     /**
      * Reads any required data for this permission from the given destination
      *
-     * @param source Data to read from
+     * @param source {@link Data} to read from
      * @return this for chaining
      */
     default Permission read(@Nullable Data source) {