add javadocs

paper-api/src/main/java/io/papermc/paper/registry/TypedKeyImpl.java

@@ -1,16 +1,19 @@
 package io.papermc.paper.registry;
 
 import net.kyori.adventure.key.Key;
+import net.kyori.adventure.key.KeyPattern;
 import org.jspecify.annotations.NullMarked;
 
 @NullMarked
 record TypedKeyImpl<T>(Key key, RegistryKey<T> registryKey) implements TypedKey<T> {
     // Wrap key methods to make this easier to use
+    @KeyPattern.Namespace
     @Override
     public String namespace() {
         return this.key.namespace();
     }
 
+    @KeyPattern.Value
     @Override
     public String value() {
         return this.key.value();

paper-api/src/main/java/io/papermc/paper/registry/data/JukeboxSongRegistryEntry.java

@@ -20,12 +20,36 @@ import org.jetbrains.annotations.Range;
 @ApiStatus.NonExtendable
 public interface JukeboxSongRegistryEntry {
 
+    /**
+     * Gets the sound event for this song.
+     *
+     * @return the sound event
+     */
+    @Contract(pure = true)
     Either<TypedKey<Sound>, SoundEventRegistryEntry> soundEvent();
 
+    /**
+     * Gets the description for this song.
+     *
+     * @return the description
+     */
+    @Contract(pure = true)
     Component description();
 
+    /**
+     * Gets the length in seconds for this song.
+     *
+     * @return the length in seconds
+     */
+    @Contract(pure = true)
     @Positive float lengthInSeconds();
 
+    /**
+     * Gets the comparator output for this song.
+     *
+     * @return the comparator output
+     */
+    @Contract(pure = true)
     @Range(from = 0, to = 15) int comparatorOutput();
 
     /**
@@ -45,18 +69,53 @@ public interface JukeboxSongRegistryEntry {
     @ApiStatus.NonExtendable
     interface Builder extends JukeboxSongRegistryEntry, RegistryBuilder<JukeboxSong> {
 
+        /**
+         * Sets the sound event for this song to a sound event present
+         * in the {@link io.papermc.paper.registry.RegistryKey#SOUND_EVENT} registry.
+         * <p>This will override {@link #soundEvent(Consumer)}</p>
+         *
+         * @param soundEvent the sound event
+         * @return this builder
+         * @see #soundEvent(Consumer)
+         */
         @Contract(value = "_ -> this", mutates = "this")
         Builder soundEvent(TypedKey<Sound> soundEvent);
 
+        /**
+         * Sets the sound event for this song to a new sound event.
+         * <p>This will override {@link #soundEvent(TypedKey)}</p>
+         *
+         * @param soundEvent the sound event
+         * @return this builder
+         * @see #soundEvent(TypedKey)
+         */
         @Contract(value = "_ -> this", mutates = "this")
         Builder soundEvent(Consumer<? super SoundEventRegistryEntry.Builder> soundEvent);
 
+        /**
+         * Sets the description for this song.
+         *
+         * @param description the description
+         * @return this builder
+         */
         @Contract(value = "_ -> this", mutates = "this")
         Builder description(Component description);
 
+        /**
+         * Sets the length in seconds for this song.
+         *
+         * @param lengthInSeconds the length in seconds (positive)
+         * @return this builder
+         */
         @Contract(value = "_ -> this", mutates = "this")
         Builder lengthInSeconds(@Positive float lengthInSeconds);
 
+        /**
+         * Sets the comparator output for this song.
+         *
+         * @param comparatorOutput the comparator output [0-15]
+         * @return this builder
+         */
         @Contract(value = "_ -> this", mutates = "this")
         Builder comparatorOutput(@Range(from = 0, to = 15) int comparatorOutput);
     }

paper-api/src/main/java/io/papermc/paper/registry/data/SoundEventRegistryEntry.java

@@ -14,9 +14,19 @@ import org.jspecify.annotations.Nullable;
 @ApiStatus.NonExtendable
 public interface SoundEventRegistryEntry {
 
+    /**
+     * Gets the resource pack location for this sound event.
+     *
+     * @return the location
+     */
     @Contract(pure = true)
     Key location();
 
+    /**
+     * Gets the fixed range for this sound event, if present.
+     *
+     * @return the fixed range, or {@code null} if not present
+     */
     @Contract(pure = true)
     @Nullable Float fixedRange();
 
@@ -32,9 +42,21 @@ public interface SoundEventRegistryEntry {
     @ApiStatus.NonExtendable
     interface Builder extends SoundEventRegistryEntry, RegistryBuilder<Sound> {
 
+        /**
+         * Sets the resource pack location for this sound event.
+         *
+         * @param location the location
+         * @return this builder
+         */
         @Contract(value = "_ -> this", mutates = "this")
         Builder location(Key location);
 
+        /**
+         * Sets the fixed range for this sound event.
+         *
+         * @param fixedRange the fixed range
+         * @return this builder
+         */
         @Contract(value = "_ -> this", mutates = "this")
         Builder fixedRange(@Nullable Float fixedRange);
     }