diff --git a/mappings/net/minecraft/util/registry/RegistryKey.mapping b/mappings/net/minecraft/util/registry/RegistryKey.mapping
index 7375a37aab..d985699aae 100644
--- a/mappings/net/minecraft/util/registry/RegistryKey.mapping
+++ b/mappings/net/minecraft/util/registry/RegistryKey.mapping
@@ -1,16 +1,47 @@
 CLASS net/minecraft/class_5321 net/minecraft/util/registry/RegistryKey
+	COMMENT Represents a key for a value in a registry in a context where a
+	COMMENT root registry is available.
+	COMMENT
+	COMMENT @param <T> the type of the value
+	COMMENT @see Registry#ROOT
 	FIELD field_25136 INSTANCES Ljava/util/Map;
-	FIELD field_25137 registryId Lnet/minecraft/class_2960;
-	FIELD field_25138 valueId Lnet/minecraft/class_2960;
+		COMMENT A cache of all registry keys ever created.
+	FIELD field_25137 registry Lnet/minecraft/class_2960;
+		COMMENT The identifier of the registry in the root registry.
+	FIELD field_25138 value Lnet/minecraft/class_2960;
+		COMMENT The identifier of the value in the registry specified by {@link #registry}.
 	METHOD <init> (Lnet/minecraft/class_2960;Lnet/minecraft/class_2960;)V
-		ARG 1 registryId
-		ARG 2 valueId
-	METHOD method_29177 getValueId ()Lnet/minecraft/class_2960;
-	METHOD method_29179 getOrCreate (Lnet/minecraft/class_5321;Lnet/minecraft/class_2960;)Lnet/minecraft/class_5321;
-		ARG 0 registryId
-		ARG 1 valueId
-	METHOD method_29180 getOrCreateRootKey (Lnet/minecraft/class_2960;)Lnet/minecraft/class_5321;
-		ARG 0 registryId
-	METHOD method_29181 getOrCreate (Lnet/minecraft/class_2960;Lnet/minecraft/class_2960;)Lnet/minecraft/class_5321;
-		ARG 0 registryId
-		ARG 1 valueId
+		ARG 1 registry
+		ARG 2 value
+	METHOD method_29177 getValue ()Lnet/minecraft/class_2960;
+	METHOD method_29178 createKeyFactory (Lnet/minecraft/class_5321;)Ljava/util/function/Function;
+		COMMENT Creates a function that converts an identifier to a registry key for the
+		COMMENT registry that {@code registry} refers to in the root registry.
+		ARG 0 registry
+			COMMENT the reference to the value-holding registry in the root registry
+	METHOD method_29179 of (Lnet/minecraft/class_5321;Lnet/minecraft/class_2960;)Lnet/minecraft/class_5321;
+		COMMENT Creates a registry key for a value in a registry with a registry key for
+		COMMENT the value-holding registry in the root registry and an identifier of the
+		COMMENT value.
+		COMMENT
+		COMMENT <p>You can call it like {@code RegistryKey.of(Registry.ITEM_KEY, new Identifier("iron_ingot"))}
+		COMMENT to create a registry key for iron ingot.</p>
+		COMMENT
+		COMMENT @param <T> the type of the value
+		ARG 0 registry
+			COMMENT the registry key of the registry in the root registry
+		ARG 1 value
+			COMMENT the identifier of the value
+	METHOD method_29180 ofRegistry (Lnet/minecraft/class_2960;)Lnet/minecraft/class_5321;
+		COMMENT Creates a registry key for a registry in the root registry (registry of
+		COMMENT all registries) with an identifier for the registry.
+		COMMENT
+		COMMENT <p>You can call it like {@code RegistryKey.of(new Identifier("block"))}
+		COMMENT to create a registry key for the block registry.</p>
+		COMMENT
+		COMMENT @param <T> the element type of the registry
+		ARG 0 registry
+			COMMENT the identifier of the registry
+	METHOD method_29181 of (Lnet/minecraft/class_2960;Lnet/minecraft/class_2960;)Lnet/minecraft/class_5321;
+		ARG 0 registry
+		ARG 1 value