Document registry (#3304)

* Document registry

* More registry javadoc

* Map more registry

* More registry javadoc

* Apply suggestions from code review

Co-authored-by: enbrain <[email protected]>

* Update mappings/net/minecraft/util/registry/RegistryEntry.mapping

Co-authored-by: enbrain <[email protected]>

mappings/net/minecraft/util/registry/BuiltinRegistries.mapping

@@ -1,9 +1,11 @@
 CLASS net/minecraft/class_5458 net/minecraft/util/registry/BuiltinRegistries
-	COMMENT Stores a few hardcoded registries with builtin values for datapack-loadable registries,
-	COMMENT from which a registry tracker can create a new dynamic registry.
+	COMMENT Stores a few hardcoded registries with builtin values for data pack-loadable registries,
+	COMMENT which are copied when starting a server. Register values here to make them available for
+	COMMENT every server run.
 	COMMENT
 	COMMENT <p>Note that these registries do not contain the actual entries that the server has,
-	COMMENT for that you will need to access it from {@link net.minecraft.util.registry.DynamicRegistryManager}.
+	COMMENT for that you will need to access it from {@link
+	COMMENT net.minecraft.util.registry.DynamicRegistryManager}.
 	COMMENT
 	COMMENT @see net.minecraft.server.MinecraftServer#getRegistryManager()
 	COMMENT @see net.minecraft.client.network.ClientPlayNetworkHandler#getRegistryManager()

mappings/net/minecraft/util/registry/DefaultedRegistry.mapping

@@ -1,4 +1,5 @@
 CLASS net/minecraft/class_2348 net/minecraft/util/registry/DefaultedRegistry
+	COMMENT An implementation of {@link Registry} with a default ID and value for unknown lookups.
 	FIELD field_11014 defaultId Lnet/minecraft/class_2960;
 	FIELD field_11015 defaultEntry Lnet/minecraft/class_6880;
 	METHOD <init> (Ljava/lang/String;Lnet/minecraft/class_5321;Lcom/mojang/serialization/Lifecycle;Ljava/util/function/Function;)V
@@ -7,3 +8,4 @@ CLASS net/minecraft/class_2348 net/minecraft/util/registry/DefaultedRegistry
 		ARG 3 lifecycle
 		ARG 4 valueToEntryFunction
 	METHOD method_10137 getDefaultId ()Lnet/minecraft/class_2960;
+		COMMENT {@return the ID of the default value}

mappings/net/minecraft/util/registry/DynamicRegistryManager.mapping

@@ -9,6 +9,14 @@ CLASS net/minecraft/class_5455 net/minecraft/util/registry/DynamicRegistryManage
 	COMMENT <p>The {@link DynamicRegistryManager.ImmutableImpl}
 	COMMENT class serves as an immutable implementation of any particular collection
 	COMMENT or configuration of dynamic registries.
+	COMMENT
+	COMMENT <p>To create a new instance, call {@link #createAndLoad}, then (optionally)
+	COMMENT load the data pack-defined values via {@link
+	COMMENT net.minecraft.util.dynamic.RegistryOps#ofLoaded(DynamicOps, DynamicRegistryManager.Mutable, net.minecraft.resource.ResourceManager)}.
+	COMMENT Values registered in {@link BuiltinRegistries} are always available.
+	COMMENT
+	COMMENT @see net.minecraft.server.MinecraftServer#getRegistryManager()
+	COMMENT @see net.minecraft.client.network.ClientPlayNetworkHandler#getRegistryManager()
 	FIELD field_25918 LOGGER Lorg/slf4j/Logger;
 	FIELD field_25919 INFOS Ljava/util/Map;
 	FIELD field_26733 BUILTIN Ljava/util/function/Supplier;
@@ -86,6 +94,11 @@ CLASS net/minecraft/class_5455 net/minecraft/util/registry/DynamicRegistryManage
 		ARG 0 entry
 	METHOD method_40313 streamSyncedRegistries ()Ljava/util/stream/Stream;
 	METHOD method_40314 createAndLoad ()Lnet/minecraft/class_5455$class_6893;
+		COMMENT {@return a new dynamic registry manager instance with all built-in registries loaded}
+		COMMENT
+		COMMENT <p>The registries do not contain values from data packs.
+		COMMENT Call {@link net.minecraft.util.dynamic.RegistryOps#ofLoaded(DynamicOps, DynamicRegistryManager.Mutable, net.minecraft.resource.ResourceManager)}
+		COMMENT to load those values.
 	METHOD method_40316 toImmutable ()Lnet/minecraft/class_5455$class_6890;
 	METHOD method_40317 createSimpleRegistry (Lnet/minecraft/class_5321;)Lnet/minecraft/class_2385;
 		ARG 0 registryRef

mappings/net/minecraft/util/registry/MutableRegistry.mapping

@@ -1,4 +1,8 @@
 CLASS net/minecraft/class_2385 net/minecraft/util/registry/MutableRegistry
+	COMMENT A registry that allows adding or modifying values.
+	COMMENT Note that in vanilla, all registries are instances of this.
+	COMMENT
+	COMMENT @see Registry
 	METHOD method_10272 add (Lnet/minecraft/class_5321;Ljava/lang/Object;Lcom/mojang/serialization/Lifecycle;)Lnet/minecraft/class_6880;
 		ARG 1 key
 		ARG 2 entry
@@ -21,3 +25,4 @@ CLASS net/minecraft/class_2385 net/minecraft/util/registry/MutableRegistry
 		ARG 3 newEntry
 		ARG 4 lifecycle
 	METHOD method_35863 isEmpty ()Z
+		COMMENT {@return whether the registry is empty}

mappings/net/minecraft/util/registry/RegistryCodecs.mapping

@@ -1,4 +1,5 @@
 CLASS net/minecraft/class_6895 net/minecraft/util/registry/RegistryCodecs
+	COMMENT A utility class for serialization of registries using codecs.
 	METHOD method_40338 (Lnet/minecraft/class_2378;)Ljava/util/Map;
 		ARG 0 registry
 	METHOD method_40339 (Lnet/minecraft/class_2385;Lcom/mojang/serialization/Lifecycle;Lnet/minecraft/class_5321;Ljava/lang/Object;)V

mappings/net/minecraft/util/registry/RegistryEntry.mapping

@@ -1,26 +1,113 @@
 CLASS net/minecraft/class_6880 net/minecraft/util/registry/RegistryEntry
+	COMMENT An object holding a value that can be registered in a registry. In most cases, the
+	COMMENT value is already registered in a registry ("reference entry"), hence the name;
+	COMMENT however, it is possible to create a registry entry by direct reference
+	COMMENT ("direct entry"). This is useful for data packs, as they can define
+	COMMENT one-time use values directly without having to register them every time.
+	COMMENT
+	COMMENT <p>Registry entries do not define {@code equals} method. Instead, compare the result
+	COMMENT of {@link #getKeyOrValue}.
+	COMMENT
+	COMMENT <p>Reference registry entries also hold their {@linkplain TagKey tags}. For more
+	COMMENT information on type-specific behaviors, including "intrusive" and "stand-alone"
+	COMMENT reference registry entries, see the respective class documentations.
+	COMMENT
+	COMMENT <p>A registry entry is sometimes referred to as a "holder" in error messages.
+	COMMENT
+	COMMENT @see RegistryEntry.Direct
+	COMMENT @see RegistryEntry.Reference
+	COMMENT @see Registry#entryOf
+	COMMENT @see Registry#getEntry
 	METHOD method_40220 isIn (Lnet/minecraft/class_6862;)Z
+		COMMENT {@return whether this entry is in {@code tag}}
+		COMMENT
+		COMMENT <p>This always returns {@code false} for direct entries, since tags are managed by
+		COMMENT a registry.
 		ARG 1 tag
 	METHOD method_40221 upcast (Lnet/minecraft/class_6880;)Lnet/minecraft/class_6880;
+		COMMENT Casts {@code RegistryEntry<? extends T>} to {@code RegistryEntry<T>}.
+		COMMENT
+		COMMENT @return the cast value
 		ARG 0 entry
 	METHOD method_40222 matchesRegistry (Lnet/minecraft/class_2378;)Z
+		COMMENT {@return whether the registry for the entry is {@code registry}}
+		COMMENT
+		COMMENT <p>This always returns {@code true} for direct entries.
 		ARG 1 registry
 	METHOD method_40223 of (Ljava/lang/Object;)Lnet/minecraft/class_6880;
+		COMMENT {@return a new direct registry entry of {@code value}}
 		ARG 0 value
 	METHOD method_40224 matches (Ljava/util/function/Predicate;)Z
+		COMMENT {@return whether this entry's key matches {@code predicate}}
+		COMMENT
+		COMMENT <p>This always returns {@code false} for direct entries.
 		ARG 1 predicate
 	METHOD method_40225 matchesKey (Lnet/minecraft/class_5321;)Z
+		COMMENT {@return whether the registry key of this entry is {@code key}}
+		COMMENT
+		COMMENT <p>This always returns {@code false} for direct entries.
 		ARG 1 key
 	METHOD method_40226 matchesId (Lnet/minecraft/class_2960;)Z
+		COMMENT {@return whether the ID of this entry is {@code id}}
+		COMMENT
+		COMMENT <p>This always returns {@code false} for direct entries.
 		ARG 1 id
 	METHOD method_40227 hasKeyAndValue ()Z
 	METHOD method_40228 streamTags ()Ljava/util/stream/Stream;
+		COMMENT {@return a stream of the tags of this entry, or an empty stream if this is a direct entry}
 	METHOD method_40229 getKeyOrValue ()Lcom/mojang/datafixers/util/Either;
+		COMMENT {@return the object that identifies this registry key}
+		COMMENT
+		COMMENT <p>For direct entries, this is the held value, and for reference entries, this is the
+		COMMENT key of the entry.
 	METHOD method_40230 getKey ()Ljava/util/Optional;
+		COMMENT {@return the registry key of this entry, or an empty optional if this is a direct entry}
 	METHOD method_40231 getType ()Lnet/minecraft/class_6880$class_6882;
+		COMMENT {@return the type (direct or reference) of this registry entry}
+		COMMENT
+		COMMENT <p>This is different from the types of reference registry entries, i.e.
+		COMMENT stand-alone or intrusive.
 	CLASS class_6881 Direct
+		COMMENT A direct registry entry holds the value directly. The value does not have to be
+		COMMENT registered in a registry. Therefore, they receive no ID or registry key, and they
+		COMMENT cannot be tagged.
+		COMMENT
+		COMMENT <p>This is most often used in data packs to inline one-time use values directly.
 	CLASS class_6882 Type
+		COMMENT The types of registry entries.
+		COMMENT
+		COMMENT @see RegistryEntry
 	CLASS class_6883 Reference
+		COMMENT A reference registry entry holds the value by reference. The value is previously
+		COMMENT registered in a registry, so they can be referred to by their registry keys.
+		COMMENT This object also holds the entry's tags.
+		COMMENT
+		COMMENT <p>There are two types of reference registry entries.
+		COMMENT
+		COMMENT <ul>
+		COMMENT <li><strong>Stand-alone</strong> registry entries are first instantiated by its key,
+		COMMENT and the value is set when registering the value. This is used by most of the registries.</li>
+		COMMENT <li><strong>Intrusive</strong> registry entries are registry entries tied to a specific
+		COMMENT registerable object at instantiation time. When instantiating those, it promises
+		COMMENT that the object is later registered - which, if broken, will result in a crash.
+		COMMENT This is used for {@link #BLOCK}, {@link #ITEM}, {@link #FLUID}, {@link #ENTITY_TYPE},
+		COMMENT and {@link #GAME_EVENT} registries. This type exists for historical reasons and is
+		COMMENT deprecated.</li>
+		COMMENT </ul>
+		COMMENT
+		COMMENT <p>Therefore, it is very important to construct any intrusive-entry type object
+		COMMENT and register at the same time. For example, a mod that conditionally registers an
+		COMMENT {@link Item} has to create an instance only if the condition is met. (See {@link Registry}
+		COMMENT for a code example.)
+		COMMENT
+		COMMENT <p>When a reference registry entry is first instantiated, it only has either the key
+		COMMENT or the value (depending on the type). They are later filled when registering the
+		COMMENT entry at {@link #setKeyAndValue}. Attempting to call methods before those fields are filled
+		COMMENT can cause a crash. Note that if you are just getting the entry from a registry, this
+		COMMENT should not be a problem.
+		COMMENT
+		COMMENT @see Registry#entryOf
+		COMMENT @see Registry#getEntry
 		FIELD field_36449 registry Lnet/minecraft/class_2378;
 		FIELD field_36450 tags Ljava/util/Set;
 		FIELD field_36451 referenceType Lnet/minecraft/class_6880$class_6883$class_6884;
@@ -32,15 +119,42 @@ CLASS net/minecraft/class_6880 net/minecraft/util/registry/RegistryEntry
 			ARG 3 registryKey
 			ARG 4 value
 		METHOD method_40233 intrusive (Lnet/minecraft/class_2378;Ljava/lang/Object;)Lnet/minecraft/class_6880$class_6883;
+			COMMENT {@return a new intrusive registry entry}
+			COMMENT
+			COMMENT <p>This should not be called manually. Call {@link Registry#entryOf} or
+			COMMENT {@link Registry#getEntry} instead.
+			COMMENT
+			COMMENT <p>Callers are responsible for filling the key later by calling {@link
+			COMMENT #setKeyAndValue}.
+			COMMENT
+			COMMENT @deprecated Intrusive holders exist for legacy reasons only.
 			ARG 0 registry
 			ARG 1 value
 		METHOD method_40234 standAlone (Lnet/minecraft/class_2378;Lnet/minecraft/class_5321;)Lnet/minecraft/class_6880$class_6883;
+			COMMENT {@return a new stand-alone registry entry}
+			COMMENT
+			COMMENT <p>This should not be called manually. Call {@link Registry#entryOf} or
+			COMMENT {@link Registry#getEntry} instead.
+			COMMENT
+			COMMENT <p>Callers are responsible for filling the value later by calling {@link
+			COMMENT #setKeyAndValue}.
 			ARG 0 registry
 			ARG 1 registryKey
 		METHOD method_40235 setTags (Ljava/util/Collection;)V
 			ARG 1 tags
 		METHOD method_40236 setKeyAndValue (Lnet/minecraft/class_5321;Ljava/lang/Object;)V
+			COMMENT Sets the key and the value of this registry entry. When instantiated, an entry has
+			COMMENT only one of them, and this is called to fill the other value. Pass the current value
+			COMMENT for the parameter corresponding to the already filled field.
+			COMMENT
+			COMMENT @throws IllegalStateException when trying to change already filled fields
 			ARG 1 key
 			ARG 2 value
 		METHOD method_40237 registryKey ()Lnet/minecraft/class_5321;
+			COMMENT {@return the registry key of this entry}
+			COMMENT
+			COMMENT @throws IllegalStateException if this is an intrusive entry and it is not initialized yet
 		CLASS class_6884 Type
+			COMMENT The types of reference registry entries.
+			COMMENT
+			COMMENT @see RegistryEntry.Reference

mappings/net/minecraft/util/registry/RegistryEntryList.mapping

@@ -1,33 +1,63 @@
 CLASS net/minecraft/class_6885 net/minecraft/util/registry/RegistryEntryList
+	COMMENT A registry entry list is an immutable list of registry entries. This, is either a direct
+	COMMENT reference to each item, or a reference to a tag. A <strong>tag</strong> is a way
+	COMMENT to dynamically define a list of registered values. Anything registered in a registry
+	COMMENT can be tagged, and each registry holds a list of tags it recognizes.
+	COMMENT
+	COMMENT <p>This can be iterated directly (i.e. {@code for (RegistryEntry<T> entry : entries)}.
+	COMMENT Note that this does not implement {@link java.util.Collection}.
+	COMMENT
+	COMMENT @see Registry
+	COMMENT @see RegistryEntry
 	METHOD method_40239 stream ()Ljava/util/stream/Stream;
+		COMMENT {@return a stream of registry entries in this list}
 	METHOD method_40240 get (I)Lnet/minecraft/class_6880;
+		COMMENT {@return the registry entry at {@code index}}
+		COMMENT
+		COMMENT @throws IndexOutOfBoundsException if the index is out of bounds
 		ARG 1 index
 	METHOD method_40241 contains (Lnet/minecraft/class_6880;)Z
+		COMMENT {@return whether {@code entry} is in this list}
 		ARG 1 entry
 	METHOD method_40242 of (Ljava/util/List;)Lnet/minecraft/class_6885$class_6886;
+		COMMENT {@return a new direct list of {@code entries}}
 		ARG 0 entries
 	METHOD method_40243 getRandom (Lnet/minecraft/class_5819;)Ljava/util/Optional;
+		COMMENT {@return a random entry of the list, or an empty optional if this list is empty}
 		ARG 1 random
 	METHOD method_40244 of (Ljava/util/function/Function;Ljava/util/List;)Lnet/minecraft/class_6885$class_6886;
+		COMMENT {@return a new direct list of {@code values} converted to a registry entry with {@code mapper}}
 		ARG 0 mapper
 		ARG 1 values
 	METHOD method_40245 of (Ljava/util/function/Function;[Ljava/lang/Object;)Lnet/minecraft/class_6885$class_6886;
+		COMMENT {@return a new direct list of {@code values} converted to a registry entry with {@code mapper}}
 		ARG 0 mapper
 		ARG 1 values
 	METHOD method_40246 of ([Lnet/minecraft/class_6880;)Lnet/minecraft/class_6885$class_6886;
+		COMMENT {@return a new direct list of {@code entries}}
 		ARG 0 entries
 	METHOD method_40247 size ()I
+		COMMENT {@return the number of entries in this list}
 	METHOD method_40248 getStorage ()Lcom/mojang/datafixers/util/Either;
+		COMMENT {@return the object that identifies this registry entry list}
+		COMMENT
+		COMMENT <p>This is the tag key for a reference list, and the backing list for a direct list.
 	METHOD method_40560 isOf (Lnet/minecraft/class_2378;)Z
+		COMMENT {@return whether the list is of entries from {@code registry}}
+		COMMENT
+		COMMENT <p>This always returns {@code true} for direct lists.
 		ARG 1 registry
 	CLASS class_6886 Direct
+		COMMENT A direct registry entry list that holds the values directly, instead of using tags.
 		FIELD field_36457 entries Ljava/util/List;
 		FIELD field_36458 entrySet Ljava/util/Set;
 		METHOD <init> (Ljava/util/List;)V
 			ARG 1 entries
 	CLASS class_6887 ListBacked
+		COMMENT An internal implementation of {@link RegistryEntryList}.
 		METHOD method_40249 getEntries ()Ljava/util/List;
 	CLASS class_6888 Named
+		COMMENT A registry entry list that references a tag from the registry.
 		FIELD field_36459 tag Lnet/minecraft/class_6862;
 		FIELD field_36460 entries Ljava/util/List;
 		FIELD field_36633 registry Lnet/minecraft/class_2378;
@@ -37,3 +67,4 @@ CLASS net/minecraft/class_6885 net/minecraft/util/registry/RegistryEntryList
 		METHOD method_40250 copyOf (Ljava/util/List;)V
 			ARG 1 entries
 		METHOD method_40251 getTag ()Lnet/minecraft/class_6862;
+			COMMENT {@return the tag key that this list references}

mappings/net/minecraft/util/registry/SimpleRegistry.mapping

@@ -1,4 +1,8 @@
 CLASS net/minecraft/class_2370 net/minecraft/util/registry/SimpleRegistry
+	COMMENT An implementation of a mutable registry. All vanilla registries use this (or its
+	COMMENT subclass, {@link DefaultedRegistry}).
+	COMMENT
+	COMMENT @see Registry
 	FIELD field_11107 idToEntry Ljava/util/Map;
 	FIELD field_11109 nextId I
 	FIELD field_25067 keyToEntry Ljava/util/Map;

src/packageDocs/java/net/minecraft/util/registry/package-info.java

@@ -0,0 +1,10 @@
+/*
+ * This file is free for everyone to use under the Creative Commons Zero license.
+ */
+
+/**
+ * Contains the registry, used to register various in-game components, and related classes.
+ *
+ * @see Registry
+ */
+package net.minecraft.util.registry;