diff --git a/mappings/net/minecraft/world/ModifiableWorld.mapping b/mappings/net/minecraft/world/ModifiableWorld.mapping
index 2286441e8d..bb9224910e 100644
--- a/mappings/net/minecraft/world/ModifiableWorld.mapping
+++ b/mappings/net/minecraft/world/ModifiableWorld.mapping
@@ -12,6 +12,27 @@ CLASS net/minecraft/class_1945 net/minecraft/world/ModifiableWorld
 		ARG 2 drop
 		ARG 3 breakingEntity
 	METHOD method_8652 setBlockState (Lnet/minecraft/class_2338;Lnet/minecraft/class_2680;I)Z
+		COMMENT Updates the block state at a position, calling appropriate callbacks.
+		COMMENT
+		COMMENT <p>When called on the server, the new block state is stored and propagated to clients and listeners as dictated
+		COMMENT by the supplied flags. Note that calling this on the client will update the world locally, but may not see the
+		COMMENT change persisted across loads. It's recommended to check whether this world is client before
+		COMMENT interacting with the world in this way.</p>
+		COMMENT
+		COMMENT <p>Accepted values of the flags are a bitset combination of the following:</p>
+		COMMENT <ul>
+		COMMENT <li>0b0000001 // 1 - PROPAGATE_CHANGE - Propagates a change event to surrounding blocks.</li>
+		COMMENT <li>0b0000010 // 2 - NOTIFY_LISTENERS - Notifies listeners and clients who need to react when the block changes</li>
+		COMMENT <li>0b0000100 // 4 - NO_REDRAW - Used in conjunction with NOTIFY_LISTENERS to suppress the render pass on clients.</li>
+		COMMENT <li>0b0001000 // 8 - REDRAW_ON_MAIN_THREAD - Forces a synchronous redraw on clients.</li>
+		COMMENT <li>0b0010000 // 16 - FORCE_STATE - Bypass virtual blockstate changes and forces the passed state to be stored as-is.</li>
+		COMMENT <li>0b0100000 // 32 - SKIP_DROPS - Prevents the previous block (container) from dropping items when destroyed.</li>
+		COMMENT <li>0b1000000 // 64 - MECHANICAL_UPDATE - Signals that this is a mechanical update, usually caused by pistons moving blocks.</li>
+		COMMENT </ul>
+		COMMENT
 		ARG 1 pos
+			COMMENT the target position
 		ARG 2 state
+			COMMENT the block state to set
 		ARG 3 flags
+			COMMENT the bitwise flag combination, as described above