Comments

src/main/java/net/minestom/server/instance/block/Block.java

@@ -13,6 +13,13 @@ import org.jglrxavpok.hephaistos.nbt.NBTCompound;
 import java.util.Map;
 import java.util.function.BiPredicate;
 
+/**
+ * Represents a block that can be placed anywhere.
+ * Block objects are expected to be reusable and therefore do not
+ * retain placement data (e.g. block position)
+ * <p>
+ * Implementations are expected to be immutable.
+ */
 public interface Block extends ProtocolObject, TagReadable, BlockConstants {
 
     <T> @NotNull Block withProperty(@NotNull BlockProperty<T> property, @NotNull T value);

src/main/java/net/minestom/server/instance/block/BlockHandler.java

@@ -7,6 +7,11 @@ import net.minestom.server.utils.BlockPosition;
 import net.minestom.server.utils.NamespaceID;
 import org.jetbrains.annotations.NotNull;
 
+/**
+ * Interface used to provide block behavior. Set with {@link Block#withHandler(BlockHandler)}.
+ * <p>
+ * Implementations are expected to be thread safe.
+ */
 public interface BlockHandler {
 
     /**