diff --git a/src/main/java/net/minestom/server/instance/block/BlockManager.java b/src/main/java/net/minestom/server/instance/block/BlockManager.java
index 89e791ef9..f0d5871e9 100644
--- a/src/main/java/net/minestom/server/instance/block/BlockManager.java
+++ b/src/main/java/net/minestom/server/instance/block/BlockManager.java
@@ -16,7 +16,7 @@ public class BlockManager {
     private BlockPlacementRule[] placementRules = new BlockPlacementRule[Short.MAX_VALUE];
 
     /**
-     * Register a custom block
+     * Register a {@link CustomBlock}
      *
      * @param customBlock the custom block to register
      * @throws IllegalArgumentException if {@param customBlock} block id is negative
@@ -30,7 +30,7 @@ public class BlockManager {
     }
 
     /**
-     * Register a block placement rule
+     * Register a {@link BlockPlacementRule}
      *
      * @param blockPlacementRule the block placement rule to register
      * @throws IllegalArgumentException if {@param blockPlacementRule} block id is negative
@@ -42,7 +42,7 @@ public class BlockManager {
     }
 
     /**
-     * Get the block placement rule of the specific block
+     * Get the {@link BlockPlacementRule} of the specific block
      *
      * @param block the block to check
      * @return the block placement rule associated with the block, null if not any
@@ -52,7 +52,7 @@ public class BlockManager {
     }
 
     /**
-     * Get the block placement rule of the specific block
+     * Get the {@link BlockPlacementRule} of the specific block
      *
      * @param blockStateId the block id to check
      * @return the block placement rule associated with the id, null if not any
@@ -63,7 +63,7 @@ public class BlockManager {
     }
 
     /**
-     * Get the CustomBlock with the specific identifier {@link CustomBlock#getIdentifier()}
+     * Get the {@link CustomBlock} with the specific identifier {@link CustomBlock#getIdentifier()}
      *
      * @param identifier the custom block identifier
      * @return the {@link CustomBlock} associated with the identifier, null if not any
@@ -73,7 +73,7 @@ public class BlockManager {
     }
 
     /**
-     * Get the CustomBlock with the specific custom block id {@link CustomBlock#getCustomBlockId()}
+     * Get the {@link CustomBlock} with the specific custom block id {@link CustomBlock#getCustomBlockId()}
      *
      * @param id the custom block id
      * @return the {@link CustomBlock} associated with the id, null if not any
diff --git a/src/main/java/net/minestom/server/instance/block/rule/BlockPlacementRule.java b/src/main/java/net/minestom/server/instance/block/rule/BlockPlacementRule.java
index 8817ef478..f2e3724a9 100644
--- a/src/main/java/net/minestom/server/instance/block/rule/BlockPlacementRule.java
+++ b/src/main/java/net/minestom/server/instance/block/rule/BlockPlacementRule.java
@@ -18,10 +18,35 @@ public abstract class BlockPlacementRule {
         this(block.getBlockId());
     }
 
+    /**
+     * Get if the block can be placed in {@code blockPosition}
+     * Can for example, be used for blocks which have to be placed on a solid block
+     *
+     * @param instance      the instance of the block
+     * @param blockPosition the position where the block is trying to get place
+     * @return true if the block placement position is valid
+     */
     public abstract boolean canPlace(Instance instance, BlockPosition blockPosition);
 
-    public abstract short blockRefresh(Instance instance, BlockPosition blockPosition, short currentID);
+    /**
+     * Called when the block state id can be updated (for instance if a neighbour block changed)
+     *
+     * @param instance       the instance of the block
+     * @param blockPosition  the block position
+     * @param currentStateID the current block state id of the block
+     * @return the updated block state id
+     */
+    public abstract short blockRefresh(Instance instance, BlockPosition blockPosition, short currentStateID);
 
+    /**
+     * Called when the block is placed
+     *
+     * @param instance  the instance of the block
+     * @param block     the block placed
+     * @param blockFace the block face
+     * @param pl        the player who placed the block
+     * @return the block state id of the placed block
+     */
     public abstract short blockPlace(Instance instance, Block block, BlockFace blockFace, Player pl);
 
     public short getBlockId() {