Comments for BlockPosition constructors + cleanup

src/main/java/net/minestom/server/data/Data.java

@@ -6,7 +6,7 @@ import java.util.Set;
 /**
  * Represents an object which contain key/value based data.
  * <p>
- * Please see {@link DataImpl} for the default implementation.
+ * See {@link DataImpl} for the default implementation.
  */
 public interface Data {
 

src/main/java/net/minestom/server/data/SerializableData.java

@@ -7,9 +7,9 @@ import net.minestom.server.utils.binary.BinaryReader;
 import net.minestom.server.utils.binary.BinaryWriter;
 
 /**
- * Represent a {@link Data} object which can be serialized and read back.
+ * Represents a {@link Data} object which can be serialized and read back.
  * <p>
- * Please see {@link SerializableDataImpl} for the default implementation.
+ * See {@link SerializableDataImpl} for the default implementation.
  */
 public interface SerializableData extends Data {
 

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

@@ -93,9 +93,9 @@ public abstract class Chunk implements Viewable, DataContainer {
     /**
      * Set a block at a position.
      * <p>
-     * This is used when the previous block has to be destroyed, meaning that it clears the previous data and update method.
+     * This is used when the previous block has to be destroyed/replaced, meaning that it clears the previous data and update method.
      * <p>
-     * WARNING: this method is not thread-safe (in order to bring performance improvement with {@link ChunkBatch} &amp; {@link BlockBatch})
+     * WARNING: this method is not thread-safe (in order to bring performance improvement with {@link ChunkBatch} and {@link BlockBatch})
      * The thread-safe version is {@link InstanceContainer#setSeparateBlocks(int, int, int, short, short, Data)} (or any similar instance methods)
      * Otherwise, you can simply do not forget to have this chunk synchronized when this is called.
      *

src/main/java/net/minestom/server/utils/BlockPosition.java

@@ -3,22 +3,50 @@ package net.minestom.server.utils;
 import java.util.Objects;
 
 // TODO: pool block positions?
+
+/**
+ * Represents the position of a block, so with integers instead of floating numbers.
+ */
 public class BlockPosition {
 
     private int x, y, z;
 
+    /**
+     * Create a new {@link BlockPosition}.
+     *
+     * @param x the block X
+     * @param y the block Y
+     * @param z the block Z
+     */
     public BlockPosition(int x, int y, int z) {
         this.x = x;
         this.y = y;
         this.z = z;
     }
 
+    /**
+     * Create a new {@link BlockPosition}.
+     * <p>
+     * Float positions are converted to block position, notably used by {@link Position#toBlockPosition()}.
+     *
+     * @param x the block X
+     * @param y the block Y
+     * @param z the block Z
+     */
     public BlockPosition(float x, float y, float z) {
+        final int castedY = (int) y;
+
         this.x = (int) Math.floor(x);
-        this.y = (int) Math.floor(y);
+        this.y = (y == castedY) ? castedY : castedY + 1;
         this.z = (int) Math.floor(z);
     }
 
+    /**
+     * Create a new {@link BlockPosition} from a {@link Vector}.
+     *
+     * @param position the position vector
+     * @see #BlockPosition(float, float, float)
+     */
     public BlockPosition(Vector position) {
         this(position.getX(), position.getY(), position.getZ());
     }