Use nullmarked in packages for api tests

.checkstyle/checkstyle_base.xml

@@ -37,6 +37,12 @@
             <property name="optional" value="false"/>
         </module>
         <module name="SuppressionCommentFilter"/>
+        <!--per-check variant: // CHECKSTYLE.OFF: CheckName ... // CHECKSTYLE.ON: CheckName-->
+        <module name="SuppressionCommentFilter">
+            <property name="offCommentFormat" value="CHECKSTYLE.OFF\: ([\w\|]+)"/>
+            <property name="onCommentFormat" value="CHECKSTYLE.ON\: ([\w\|]+)"/>
+            <property name="checkFormat" value="$1"/>
+        </module>
 
         <!--Annotations-->
         <module name="AnnotationOnSameLine">
@@ -93,7 +99,6 @@
         <module name="UnnecessaryNullCheckWithInstanceOf"/>
         <module name="UnnecessarySemicolonAfterOuterTypeDeclaration"/>
         <module name="UnnecessarySemicolonAfterTypeMemberDeclaration"/>
-        <module name="UnnecessarySemicolonInEnumeration"/>
         <module name="UnnecessarySemicolonInTryWithResources"/>
         <module name="UnusedCatchParameterShouldBeUnnamed"/>
         <module name="UnusedLocalVariable"/>
@@ -163,6 +168,12 @@
         <module name="NoCodeInFile"/>
         <module name="NumericalPrefixesInfixesSuffixesCharacterCase"/>
         <module name="OuterTypeFilename"/>
+        <!--Leftover Paper/Spigot markers from when these sources were patches on top of upstream (suppressed for the patched paper-server/src/minecraft sources)-->
+        <module name="TodoComment">
+            <property name="id" value="PatchMarkerComment"/>
+            <property name="format" value="(^|//)\s*(Paper|Spigot)\b"/>
+            <message key="todo.match" value="Remove the leftover ''// Paper'' or ''// Spigot'' patch marker comment."/>
+        </module>
         <module name="UpperEll"/>
 
         <!--Modifiers-->

.checkstyle/suppressions.xml

@@ -3,5 +3,4 @@
     "https://checkstyle.org/dtds/suppressions_1_2.dtd">
 <suppressions>
     <suppress checks="MissingJavadoc.*" files="src[\\/]test[\\/]java[^\\/]*[\\/].*"/>
-    <suppress checks="JavadocPackage" files="src[\\/]test[\\/]java[^\\/]*[\\/].*"/>
 </suppressions>

build.gradle.kts

@@ -1,5 +1,3 @@
-import io.papermc.paperweight.checkstyle.PaperCheckstyleExt
-import io.papermc.paperweight.checkstyle.tasks.PaperCheckstyleTask
 import org.gradle.api.tasks.testing.logging.TestExceptionFormat
 import org.gradle.api.tasks.testing.logging.TestLogEvent
 
@@ -11,6 +9,7 @@ subprojects {
     apply {
         plugin("java-library")
         plugin("maven-publish")
+        plugin("io.papermc.paperweight.paper-checkstyle")
     }
 
     extensions.configure<JavaPluginExtension> {
@@ -19,27 +18,8 @@ subprojects {
         }
     }
 
-    val tempDisabled = setOf("paper-server", "paper-generator", "test-plugin")
-
-    if (name !in tempDisabled) {
-        apply { plugin("io.papermc.paperweight.paper-checkstyle") }
-        extensions.configure<PaperCheckstyleExt> {
-            typeUseAnnotationsFile.set(rootProject.layout.projectDirectory.file(".checkstyle/type_use_annotations.txt"))
-        }
-
-        /*tasks.withType<PaperCheckstyleTask>().configureEach {
-            configDirectory = rootProject.layout.projectDirectory.dir(".checkstyle")
-            // configFile = layout.projectDirectory.file(".checkstyle/checkstyle.xml").asFile // use the base file if not overwritten
-            maxHeapSize = "2g"
-            reports {
-                xml.required = true
-                html.required = true
-            }
-        }*/
-
-        dependencies {
-            "checkstyle"(project(":paper-checkstyle"))
-        }
+    dependencies {
+        "checkstyle"(project(":paper-checkstyle"))
     }
 }
 

paper-api/.checkstyle/checkstyle.xml

@@ -2,6 +2,11 @@
     "-//Checkstyle//DTD Checkstyle Configuration 1.3//EN"
     "https://checkstyle.org/dtds/configuration_1_3.dtd">
 <module name="Checker">
+    <!--generated sources are written by the generator, so we don't control their format-->
+    <module name="BeforeExecutionExclusionFileFilter">
+        <property name="fileNamePattern" value="[\\/]paper-api[\\/]src[\\/]generated[\\/]"/>
+    </module>
+
     <!--Single Suppression Filters-->
     <module name="io.papermc.checkstyle.filters.BetterSuppressionSingleFilter">
         <property name="checks" value="Javadoc(Method|Type)"/>

paper-api/.checkstyle/ignored_directories.txt

@@ -1,121 +1,59 @@
-paper-api/src/generated/java/com/destroystokyo/paper/entity/ai/
-paper-api/src/generated/java/io/papermc/paper/registry/keys/
-paper-api/src/generated/java/io/papermc/paper/registry/keys/tags/
 paper-api/src/main/java/co/aikar/timings/
 paper-api/src/main/java/co/aikar/util/
 paper-api/src/main/java/com/destroystokyo/paper/
-paper-api/src/main/java/com/destroystokyo/paper/block/
-paper-api/src/main/java/com/destroystokyo/paper/brigadier/
-paper-api/src/main/java/com/destroystokyo/paper/entity/
 paper-api/src/main/java/com/destroystokyo/paper/entity/ai/
-paper-api/src/main/java/com/destroystokyo/paper/entity/villager/
 paper-api/src/main/java/com/destroystokyo/paper/event/block/
-paper-api/src/main/java/com/destroystokyo/paper/event/brigadier/
 paper-api/src/main/java/com/destroystokyo/paper/event/entity/
-paper-api/src/main/java/com/destroystokyo/paper/event/inventory/
 paper-api/src/main/java/com/destroystokyo/paper/event/player/
 paper-api/src/main/java/com/destroystokyo/paper/event/profile/
 paper-api/src/main/java/com/destroystokyo/paper/event/server/
 paper-api/src/main/java/com/destroystokyo/paper/exception/
-paper-api/src/main/java/com/destroystokyo/paper/inventory/meta/
 paper-api/src/main/java/com/destroystokyo/paper/loottable/
-paper-api/src/main/java/com/destroystokyo/paper/network/
-paper-api/src/main/java/com/destroystokyo/paper/profile/
-paper-api/src/main/java/com/destroystokyo/paper/util/
-paper-api/src/main/java/com/destroystokyo/paper/utils/
-paper-api/src/main/java/io/papermc/paper/advancement/
-paper-api/src/main/java/io/papermc/paper/annotation/
-paper-api/src/main/java/io/papermc/paper/ban/
 paper-api/src/main/java/io/papermc/paper/block/
 paper-api/src/main/java/io/papermc/paper/block/bed/
-paper-api/src/main/java/io/papermc/paper/block/fluid/
-paper-api/src/main/java/io/papermc/paper/block/fluid/type/
-paper-api/src/main/java/io/papermc/paper/brigadier/
-paper-api/src/main/java/io/papermc/paper/chat/
-paper-api/src/main/java/io/papermc/paper/command/
 paper-api/src/main/java/io/papermc/paper/command/brigadier/
 paper-api/src/main/java/io/papermc/paper/command/brigadier/argument/
-paper-api/src/main/java/io/papermc/paper/command/brigadier/argument/position/
-paper-api/src/main/java/io/papermc/paper/command/brigadier/argument/predicate/
 paper-api/src/main/java/io/papermc/paper/command/brigadier/argument/range/
 paper-api/src/main/java/io/papermc/paper/command/brigadier/argument/resolvers/
 paper-api/src/main/java/io/papermc/paper/command/brigadier/argument/resolvers/selector/
-paper-api/src/main/java/io/papermc/paper/configuration/
 paper-api/src/main/java/io/papermc/paper/connection/
 paper-api/src/main/java/io/papermc/paper/datacomponent/
 paper-api/src/main/java/io/papermc/paper/datacomponent/item/
-paper-api/src/main/java/io/papermc/paper/datacomponent/item/attribute/
 paper-api/src/main/java/io/papermc/paper/datacomponent/item/blocksattacks/
 paper-api/src/main/java/io/papermc/paper/datacomponent/item/consumable/
 paper-api/src/main/java/io/papermc/paper/datapack/
-paper-api/src/main/java/io/papermc/paper/dialog/
-paper-api/src/main/java/io/papermc/paper/enchantments/
 paper-api/src/main/java/io/papermc/paper/entity/
-paper-api/src/main/java/io/papermc/paper/entity/poi/
 paper-api/src/main/java/io/papermc/paper/event/block/
-paper-api/src/main/java/io/papermc/paper/event/connection/
 paper-api/src/main/java/io/papermc/paper/event/connection/configuration/
 paper-api/src/main/java/io/papermc/paper/event/entity/
-paper-api/src/main/java/io/papermc/paper/event/executor/
-paper-api/src/main/java/io/papermc/paper/event/inventory/
 paper-api/src/main/java/io/papermc/paper/event/packet/
 paper-api/src/main/java/io/papermc/paper/event/player/
-paper-api/src/main/java/io/papermc/paper/event/server/
-paper-api/src/main/java/io/papermc/paper/event/world/
 paper-api/src/main/java/io/papermc/paper/event/world/border/
-paper-api/src/main/java/io/papermc/paper/generated/
-paper-api/src/main/java/io/papermc/paper/inventory/
-paper-api/src/main/java/io/papermc/paper/inventory/tooltip/
-paper-api/src/main/java/io/papermc/paper/item/
-paper-api/src/main/java/io/papermc/paper/persistence/
-paper-api/src/main/java/io/papermc/paper/plugin/
-paper-api/src/main/java/io/papermc/paper/plugin/bootstrap/
-paper-api/src/main/java/io/papermc/paper/plugin/configuration/
 paper-api/src/main/java/io/papermc/paper/plugin/lifecycle/event/
-paper-api/src/main/java/io/papermc/paper/plugin/lifecycle/event/handler/
 paper-api/src/main/java/io/papermc/paper/plugin/lifecycle/event/handler/configuration/
 paper-api/src/main/java/io/papermc/paper/plugin/lifecycle/event/registrar/
 paper-api/src/main/java/io/papermc/paper/plugin/lifecycle/event/types/
-paper-api/src/main/java/io/papermc/paper/plugin/loader/
-paper-api/src/main/java/io/papermc/paper/plugin/loader/library/
-paper-api/src/main/java/io/papermc/paper/plugin/loader/library/impl/
 paper-api/src/main/java/io/papermc/paper/plugin/provider/classloader/
-paper-api/src/main/java/io/papermc/paper/plugin/provider/entrypoint/
-paper-api/src/main/java/io/papermc/paper/plugin/provider/util/
 paper-api/src/main/java/io/papermc/paper/potion/
-paper-api/src/main/java/io/papermc/paper/raytracing/
 paper-api/src/main/java/io/papermc/paper/registry/
 paper-api/src/main/java/io/papermc/paper/registry/data/
-paper-api/src/main/java/io/papermc/paper/registry/data/client/
 paper-api/src/main/java/io/papermc/paper/registry/data/dialog/
-paper-api/src/main/java/io/papermc/paper/registry/data/dialog/action/
 paper-api/src/main/java/io/papermc/paper/registry/data/dialog/body/
 paper-api/src/main/java/io/papermc/paper/registry/data/dialog/input/
 paper-api/src/main/java/io/papermc/paper/registry/data/dialog/type/
 paper-api/src/main/java/io/papermc/paper/registry/event/
-paper-api/src/main/java/io/papermc/paper/registry/event/type/
-paper-api/src/main/java/io/papermc/paper/registry/holder/
 paper-api/src/main/java/io/papermc/paper/registry/set/
-paper-api/src/main/java/io/papermc/paper/registry/tag/
 paper-api/src/main/java/io/papermc/paper/scoreboard/numbers/
 paper-api/src/main/java/io/papermc/paper/tag/
-paper-api/src/main/java/io/papermc/paper/text/
-paper-api/src/main/java/io/papermc/paper/threadedregions/
 paper-api/src/main/java/io/papermc/paper/threadedregions/scheduler/
 paper-api/src/main/java/io/papermc/paper/util/
-paper-api/src/main/java/io/papermc/paper/world/
 paper-api/src/main/java/io/papermc/paper/world/damagesource/
-paper-api/src/main/java/io/papermc/paper/world/flag/
 paper-api/src/main/java/org/bukkit/
 paper-api/src/main/java/org/bukkit/advancement/
 paper-api/src/main/java/org/bukkit/attribute/
-paper-api/src/main/java/org/bukkit/ban/
 paper-api/src/main/java/org/bukkit/block/
-paper-api/src/main/java/org/bukkit/block/banner/
 paper-api/src/main/java/org/bukkit/block/data/
 paper-api/src/main/java/org/bukkit/block/data/type/
-paper-api/src/main/java/org/bukkit/block/sign/
-paper-api/src/main/java/org/bukkit/block/spawner/
 paper-api/src/main/java/org/bukkit/block/structure/
 paper-api/src/main/java/org/bukkit/boss/
 paper-api/src/main/java/org/bukkit/command/
@@ -128,12 +66,9 @@ paper-api/src/main/java/org/bukkit/damage/
 paper-api/src/main/java/org/bukkit/enchantments/
 paper-api/src/main/java/org/bukkit/entity/
 paper-api/src/main/java/org/bukkit/entity/boat/
-paper-api/src/main/java/org/bukkit/entity/memory/
 paper-api/src/main/java/org/bukkit/entity/minecart/
 paper-api/src/main/java/org/bukkit/event/
 paper-api/src/main/java/org/bukkit/event/block/
-paper-api/src/main/java/org/bukkit/event/command/
-paper-api/src/main/java/org/bukkit/event/enchantment/
 paper-api/src/main/java/org/bukkit/event/entity/
 paper-api/src/main/java/org/bukkit/event/hanging/
 paper-api/src/main/java/org/bukkit/event/inventory/
@@ -151,51 +86,28 @@ paper-api/src/main/java/org/bukkit/inventory/meta/
 paper-api/src/main/java/org/bukkit/inventory/meta/components/
 paper-api/src/main/java/org/bukkit/inventory/meta/tags/
 paper-api/src/main/java/org/bukkit/inventory/meta/trim/
-paper-api/src/main/java/org/bukkit/inventory/recipe/
 paper-api/src/main/java/org/bukkit/inventory/view/
 paper-api/src/main/java/org/bukkit/inventory/view/builder/
 paper-api/src/main/java/org/bukkit/loot/
 paper-api/src/main/java/org/bukkit/map/
 paper-api/src/main/java/org/bukkit/material/
-paper-api/src/main/java/org/bukkit/material/types/
 paper-api/src/main/java/org/bukkit/metadata/
-paper-api/src/main/java/org/bukkit/packs/
 paper-api/src/main/java/org/bukkit/permissions/
 paper-api/src/main/java/org/bukkit/persistence/
 paper-api/src/main/java/org/bukkit/plugin/
 paper-api/src/main/java/org/bukkit/plugin/java/
 paper-api/src/main/java/org/bukkit/plugin/messaging/
 paper-api/src/main/java/org/bukkit/potion/
-paper-api/src/main/java/org/bukkit/profile/
-paper-api/src/main/java/org/bukkit/projectiles/
 paper-api/src/main/java/org/bukkit/scheduler/
 paper-api/src/main/java/org/bukkit/scoreboard/
 paper-api/src/main/java/org/bukkit/spawner/
 paper-api/src/main/java/org/bukkit/structure/
-paper-api/src/main/java/org/bukkit/tag/
 paper-api/src/main/java/org/bukkit/util/
 paper-api/src/main/java/org/bukkit/util/io/
 paper-api/src/main/java/org/bukkit/util/noise/
 paper-api/src/main/java/org/bukkit/util/permissions/
-paper-api/src/main/java/org/spigotmc/
-paper-api/src/main/java/org/spigotmc/event/player/
-paper-api/src/test/java/com/destroystokyo/paper/
-paper-api/src/test/java/io/papermc/paper/adventure/
-paper-api/src/test/java/io/papermc/paper/registry/
-paper-api/src/test/java/io/papermc/paper/testing/
-paper-api/src/test/java/io/papermc/paper/util/
 paper-api/src/test/java/org/bukkit/
 paper-api/src/test/java/org/bukkit/configuration/
-paper-api/src/test/java/org/bukkit/configuration/file/
 paper-api/src/test/java/org/bukkit/conversations/
-paper-api/src/test/java/org/bukkit/event/
-paper-api/src/test/java/org/bukkit/materials/
 paper-api/src/test/java/org/bukkit/metadata/
-paper-api/src/test/java/org/bukkit/plugin/
-paper-api/src/test/java/org/bukkit/plugin/messaging/
-paper-api/src/test/java/org/bukkit/scoreboard/
-paper-api/src/test/java/org/bukkit/support/
-paper-api/src/test/java/org/bukkit/support/provider/
-paper-api/src/test/java/org/bukkit/support/test/
 paper-api/src/test/java/org/bukkit/util/
-paper-api/src/test/java/org/bukkit/util/io/

paper-api/build.gradle.kts

@@ -183,11 +183,6 @@ val generateApiVersioningFile = tasks.register<GenerateApiVersioningFile>("gener
 
 tasks.jar {
     from(generateApiVersioningFile.flatMap { it.outputFile })
-    manifest {
-        attributes(
-            "Automatic-Module-Name" to "org.bukkit"
-        )
-    }
 }
 
 abstract class Services {

paper-api/src/main/java/com/destroystokyo/paper/block/BlockSoundGroup.java

@@ -2,63 +2,58 @@ package com.destroystokyo.paper.block;
 
 import org.bukkit.Sound;
 import org.bukkit.block.Block;
-import org.jetbrains.annotations.NotNull;
 
 /**
- * Represents the sounds that a {@link Block} makes in certain situations
+ * Represents the sounds that a {@link Block} makes in certain situations.
  * <p>
  * The sound group includes break, step, place, hit, and fall sounds.
+ *
  * @deprecated use {@link org.bukkit.SoundGroup}
  */
 @Deprecated(forRemoval = true, since = "1.18.2")
 public interface BlockSoundGroup {
     /**
-     * Gets the sound that plays when breaking this block
+     * Gets the sound that plays when breaking this block.
      *
      * @return The break sound
      * @deprecated use {@link org.bukkit.SoundGroup#getBreakSound()}
      */
-    @NotNull
     @Deprecated(forRemoval = true, since = "1.18.2")
     Sound getBreakSound();
 
     /**
-     * Gets the sound that plays when stepping on this block
+     * Gets the sound that plays when stepping on this block.
      *
      * @return The step sound
      * @deprecated use {@link org.bukkit.SoundGroup#getStepSound()}
      */
-    @NotNull
     @Deprecated(forRemoval = true, since = "1.18.2")
     Sound getStepSound();
 
     /**
-     * Gets the sound that plays when placing this block
+     * Gets the sound that plays when placing this block.
      *
      * @return The place sound
      * @deprecated use {@link org.bukkit.SoundGroup#getPlaceSound()}
      */
-    @NotNull
     @Deprecated(forRemoval = true, since = "1.18.2")
     Sound getPlaceSound();
 
     /**
-     * Gets the sound that plays when hitting this block
+     * Gets the sound that plays when hitting this block.
      *
      * @return The hit sound
      * @deprecated use {@link org.bukkit.SoundGroup#getHitSound()}
      */
-    @NotNull
     @Deprecated(forRemoval = true, since = "1.18.2")
     Sound getHitSound();
 
     /**
-     * Gets the sound that plays when this block falls
+     * Gets the sound that plays when this block falls.
      *
      * @return The fall sound
      * @deprecated use {@link org.bukkit.SoundGroup#getFallSound()}
      */
-    @NotNull
     @Deprecated(forRemoval = true, since = "1.18.2")
     Sound getFallSound();
 }

paper-api/src/main/java/com/destroystokyo/paper/block/TargetBlockInfo.java

@@ -3,10 +3,10 @@ package com.destroystokyo.paper.block;
 import org.bukkit.FluidCollisionMode;
 import org.bukkit.block.Block;
 import org.bukkit.block.BlockFace;
-import org.jetbrains.annotations.NotNull;
 
 /**
- * Represents information about a targeted block
+ * Represents information about a targeted block.
+ *
  * @deprecated use {@link org.bukkit.util.RayTraceResult}
  */
 @Deprecated(forRemoval = true, since = "1.19.3")
@@ -14,42 +14,41 @@ public class TargetBlockInfo {
     private final Block block;
     private final BlockFace blockFace;
 
-    public TargetBlockInfo(@NotNull Block block, @NotNull BlockFace blockFace) {
+    public TargetBlockInfo(final Block block, final BlockFace blockFace) {
         this.block = block;
         this.blockFace = blockFace;
     }
 
     /**
-     * Get the block that is targeted
+     * Get the block that is targeted.
      *
      * @return Targeted block
      */
-    @NotNull
     public Block getBlock() {
-        return block;
+        return this.block;
     }
 
     /**
-     * Get the targeted BlockFace
+     * Get the targeted BlockFace.
      *
      * @return Targeted blockface
      */
-    @NotNull
     public BlockFace getBlockFace() {
-        return blockFace;
+        return this.blockFace;
     }
 
     /**
-     * Get the relative Block to the targeted block on the side it is targeted at
+     * Get the relative Block to the targeted block on the side it is targeted at.
      *
      * @return Block relative to targeted block
      */
-    @NotNull
     public Block getRelativeBlock() {
-        return block.getRelative(blockFace);
+        return this.block.getRelative(this.blockFace);
     }
 
     /**
+     * Determines whether fluids are considered when targeting a block.
+     *
      * @deprecated use {@link org.bukkit.FluidCollisionMode}
      */
     @Deprecated(forRemoval = true, since = "1.19.3")
@@ -60,7 +59,7 @@ public class TargetBlockInfo {
 
         public final FluidCollisionMode bukkit;
 
-        FluidMode(FluidCollisionMode bukkit) {
+        FluidMode(final FluidCollisionMode bukkit) {
             this.bukkit = bukkit;
         }
     }

paper-api/src/main/java/com/destroystokyo/paper/block/package-info.java

@@ -0,0 +1,7 @@
+/**
+ * Deprecated block API, replaced by {@link org.bukkit.SoundGroup} and {@link org.bukkit.util.RayTraceResult}.
+ */
+@NullMarked
+package com.destroystokyo.paper.block;
+
+import org.jspecify.annotations.NullMarked;

paper-api/src/main/java/com/destroystokyo/paper/brigadier/BukkitBrigadierCommand.java

@@ -2,7 +2,6 @@ package com.destroystokyo.paper.brigadier;
 
 import com.mojang.brigadier.Command;
 import com.mojang.brigadier.suggestion.SuggestionProvider;
-
 import java.util.function.Predicate;
 
 /**
@@ -12,5 +11,5 @@ import java.util.function.Predicate;
  * @deprecated For removal, see {@link io.papermc.paper.command.brigadier.Commands} on how to use the new Brigadier API.
  */
 @Deprecated(forRemoval = true, since = "1.20.6")
-public interface BukkitBrigadierCommand <S extends BukkitBrigadierCommandSource> extends Command<S>, Predicate<S>, SuggestionProvider<S> {
+public interface BukkitBrigadierCommand<S extends BukkitBrigadierCommandSource> extends Command<S>, Predicate<S>, SuggestionProvider<S> {
 }

paper-api/src/main/java/com/destroystokyo/paper/brigadier/BukkitBrigadierCommandSource.java

@@ -4,22 +4,21 @@ import org.bukkit.Location;
 import org.bukkit.World;
 import org.bukkit.command.CommandSender;
 import org.bukkit.entity.Entity;
-import org.jetbrains.annotations.Nullable;
+import org.jspecify.annotations.Nullable;
 
 /**
+ * A command source that exposes its Bukkit equivalents.
+ *
  * @deprecated For removal, see {@link io.papermc.paper.command.brigadier.Commands} on how to use the new Brigadier API.
  */
 @Deprecated(forRemoval = true)
 public interface BukkitBrigadierCommandSource {
 
-    @Nullable
-    Entity getBukkitEntity();
+    @Nullable Entity getBukkitEntity();
 
-    @Nullable
-    World getBukkitWorld();
+    @Nullable World getBukkitWorld();
 
-    @Nullable
-    Location getBukkitLocation();
+    @Nullable Location getBukkitLocation();
 
     CommandSender getBukkitSender();
 }

paper-api/src/main/java/com/destroystokyo/paper/brigadier/package-info.java

@@ -0,0 +1,7 @@
+/**
+ * Deprecated Brigadier integration, replaced by {@link io.papermc.paper.command.brigadier.Commands}.
+ */
+@NullMarked
+package com.destroystokyo.paper.brigadier;
+
+import org.jspecify.annotations.NullMarked;

paper-api/src/main/java/com/destroystokyo/paper/entity/Pathfinder.java

@@ -2,37 +2,39 @@ package com.destroystokyo.paper.entity;
 
 import java.util.List;
 import org.bukkit.Location;
-import org.bukkit.entity.LivingEntity;
 import org.bukkit.entity.Entity;
+import org.bukkit.entity.LivingEntity;
 import org.bukkit.entity.Mob;
 import org.checkerframework.checker.index.qual.NonNegative;
-import org.jspecify.annotations.NullMarked;
 import org.jspecify.annotations.Nullable;
 
 /**
- * Handles pathfinding operations for an Entity
+ * Handles pathfinding operations for an Entity.
  */
-@NullMarked
 public interface Pathfinder {
 
     /**
+     * Gets the entity that is controlled by this pathfinder.
+     *
      * @return The entity that is controlled by this pathfinder
      */
     Mob getEntity();
 
     /**
-     * Instructs the Entity to stop trying to navigate to its current desired location
+     * Instructs the Entity to stop trying to navigate to its current desired location.
      */
     void stopPathfinding();
 
     /**
-     * If the entity is currently trying to navigate to a destination, this will return true
+     * If the entity is currently trying to navigate to a destination, this will return true.
      *
      * @return true if the entity is navigating to a destination
      */
     boolean hasPath();
 
     /**
+     * Gets the path the entity is currently following.
+     *
      * @return The location the entity is trying to navigate to, or null if there is no destination
      */
     @Nullable PathResult getCurrentPath();
@@ -44,7 +46,7 @@ public interface Pathfinder {
      * @param loc Location to navigate to
      * @return The closest Location the Entity can get to for this navigation, or null if no path could be calculated
      */
-    default @Nullable PathResult findPath(Location loc) {
+    default @Nullable PathResult findPath(final Location loc) {
         return this.findPath(loc, 0);
     }
 
@@ -52,12 +54,12 @@ public interface Pathfinder {
      * Calculates a destination for the Entity to navigate to, but does not set it
      * as the current target. Useful for calculating what would happen before setting it.
      *
-     * @param loc Location to navigate to
+     * @param loc        Location to navigate to
      * @param reachRange The <a href="https://cp-algorithms.com/geometry/manhattan-distance.html">Manhattan-distance</a> threshold
      *                   from the target position at which the path is considered reached, where {@code 0} requires the exact target position
      * @return The closest Location the Entity can get to for this navigation, or null if no path could be calculated
      */
-    @Nullable PathResult findPath(final Location loc, final @NonNegative int reachRange);
+    @Nullable PathResult findPath(Location loc, @NonNegative int reachRange);
 
     /**
      * Calculates a destination for the Entity to navigate to reach the target entity,
@@ -72,8 +74,7 @@ public interface Pathfinder {
      * @param target the Entity to navigate to
      * @return The closest Location the Entity can get to for this navigation, or null if no path could be calculated
      */
-    @Nullable
-    default PathResult findPath(LivingEntity target) {
+    default @Nullable PathResult findPath(final LivingEntity target) {
         return this.findPath((Entity) target);
     }
 
@@ -90,7 +91,7 @@ public interface Pathfinder {
      * @param target the Entity to navigate to
      * @return The closest Location the Entity can get to for this navigation, or null if no path could be calculated
      */
-    default @Nullable PathResult findPath(Entity target) {
+    default @Nullable PathResult findPath(final Entity target) {
         return this.findPath(target, 0);
     }
 
@@ -104,12 +105,12 @@ public interface Pathfinder {
      * <p>
      * However, this behavior is not guaranteed, and is subject to the games behavior.
      *
-     * @param target the Entity to navigate to
+     * @param target     the Entity to navigate to
      * @param reachRange The <a href="https://cp-algorithms.com/geometry/manhattan-distance.html">Manhattan-distance</a> threshold
      *                   from the target position at which the path is considered reached, where {@code 0} requires the exact target position
      * @return The closest Location the Entity can get to for this navigation, or null if no path could be calculated
      */
-    @Nullable PathResult findPath(final Entity target, final @NonNegative int reachRange);
+    @Nullable PathResult findPath(Entity target, @NonNegative int reachRange);
 
     /**
      * Calculates a destination for the Entity to navigate to, and sets it with default speed
@@ -118,7 +119,7 @@ public interface Pathfinder {
      * @param loc Location to navigate to
      * @return If the pathfinding was successfully started
      */
-    default boolean moveTo(Location loc) {
+    default boolean moveTo(final Location loc) {
         return this.moveTo(loc, 1);
     }
 
@@ -130,8 +131,8 @@ public interface Pathfinder {
      * @param speed Speed multiplier to navigate at, where 1 is 'normal'
      * @return If the pathfinding was successfully started
      */
-    default boolean moveTo(Location loc, double speed) {
-        PathResult path = this.findPath(loc);
+    default boolean moveTo(final Location loc, final double speed) {
+        final PathResult path = this.findPath(loc);
         return path != null && this.moveTo(path, speed);
     }
 
@@ -147,7 +148,7 @@ public interface Pathfinder {
      * @param target the Entity to navigate to
      * @return If the pathfinding was successfully started
      */
-    default boolean moveTo(LivingEntity target) {
+    default boolean moveTo(final LivingEntity target) {
         return this.moveTo(target, 1);
     }
 
@@ -164,7 +165,7 @@ public interface Pathfinder {
      * @param speed  Speed multiplier to navigate at, where 1 is 'normal'
      * @return If the pathfinding was successfully started
      */
-    default boolean moveTo(LivingEntity target, double speed) {
+    default boolean moveTo(final LivingEntity target, final double speed) {
         return this.moveTo((Entity) target, speed);
     }
 
@@ -180,7 +181,7 @@ public interface Pathfinder {
      * @param target the Entity to navigate to
      * @return If the pathfinding was successfully started
      */
-    default boolean moveTo(Entity target) {
+    default boolean moveTo(final Entity target) {
         return this.moveTo(target, 1);
     }
 
@@ -197,8 +198,8 @@ public interface Pathfinder {
      * @param speed  Speed multiplier to navigate at, where 1 is 'normal'
      * @return If the pathfinding was successfully started
      */
-    default boolean moveTo(Entity target, double speed) {
-        PathResult path = this.findPath(target);
+    default boolean moveTo(final Entity target, final double speed) {
+        final PathResult path = this.findPath(target);
         return path != null && this.moveTo(path, speed);
     }
 
@@ -209,13 +210,13 @@ public interface Pathfinder {
      * @param path The Path to start following
      * @return If the pathfinding was successfully started
      */
-    default boolean moveTo(PathResult path) {
+    default boolean moveTo(final PathResult path) {
         return this.moveTo(path, 1);
     }
 
     /**
      * Takes the result of a previous pathfinding calculation and sets it
-     * as the active pathfinding,
+     * as the active pathfinding.
      *
      * @param path  The Path to start following
      * @param speed Speed multiplier to navigate at, where 1 is 'normal'
@@ -231,7 +232,7 @@ public interface Pathfinder {
     boolean canOpenDoors();
 
     /**
-     * Allows this pathfinder to pass through closed doors, or not
+     * Allows this pathfinder to pass through closed doors, or not.
      *
      * @param canOpenDoors if the mob can pass through closed doors, or not
      */
@@ -245,33 +246,33 @@ public interface Pathfinder {
     boolean canPassDoors();
 
     /**
-     * Allows this pathfinder to pass through open doors, or not
+     * Allows this pathfinder to pass through open doors, or not.
      *
      * @param canPassDoors if the mob can pass through open doors, or not
      */
     void setCanPassDoors(boolean canPassDoors);
 
     /**
-     * Checks if this pathfinder assumes that the mob can float
+     * Checks if this pathfinder assumes that the mob can float.
      *
      * @return if this pathfinder assumes that the mob can float
      */
     boolean canFloat();
 
     /**
-     * Makes this pathfinder assume that the mob can float, or not
+     * Makes this pathfinder assume that the mob can float, or not.
      *
      * @param canFloat if the mob can float, or not
      */
     void setCanFloat(boolean canFloat);
 
     /**
-     * Represents the result of a pathfinding calculation
+     * Represents the result of a pathfinding calculation.
      */
     interface PathResult {
 
         /**
-         * All currently calculated points to follow along the path to reach the destination location
+         * All currently calculated points to follow along the path to reach the destination location.
          * <p>
          * Will return points the entity has already moved past, see {@link #getNextPointIndex()}
          *
@@ -280,23 +281,29 @@ public interface Pathfinder {
         List<Location> getPoints();
 
         /**
-         * @return Returns the index of the current point along the points returned in {@link #getPoints()} the entity
+         * Gets the index of the current point along the points returned in {@link #getPoints()} the entity
          * is trying to reach. This value will be higher than the maximum index of {@link #getPoints()} if this path finding is done.
+         *
+         * @return the index of the next point
          */
         int getNextPointIndex();
 
         /**
+         * Gets the next location in the path points the entity is trying to reach.
+         *
          * @return The next location in the path points the entity is trying to reach, or null if there is no next point
          */
         @Nullable Location getNextPoint();
 
         /**
+         * Gets the closest point the path can get to the target location.
+         *
          * @return The closest point the path can get to the target location
          */
         @Nullable Location getFinalPoint();
 
         /**
-         * Checks whether the final point can be reached
+         * Checks whether the final point can be reached.
          *
          * @return whether the final point can be reached
          * @see #getFinalPoint()

paper-api/src/main/java/com/destroystokyo/paper/entity/RangedEntity.java

@@ -2,10 +2,12 @@ package com.destroystokyo.paper.entity;
 
 import org.bukkit.entity.LivingEntity;
 import org.bukkit.entity.Mob;
-import org.jspecify.annotations.NullMarked;
 
-@NullMarked
+/**
+ * A mob that can perform ranged attacks.
+ */
 public interface RangedEntity extends Mob {
+
     /**
      * Attack the specified entity using a ranged attack.
      *
@@ -16,7 +18,7 @@ public interface RangedEntity extends Mob {
     void rangedAttack(LivingEntity target, float charge);
 
     /**
-     * Sets that the Entity is "charging" up an attack, by raising its hands
+     * Sets that the Entity is "charging" up an attack, by raising its hands.
      *
      * @param raiseHands Whether the entities hands are raised to charge attack
      * @deprecated use {@link #setAggressive(boolean)}
@@ -25,7 +27,8 @@ public interface RangedEntity extends Mob {
     void setChargingAttack(boolean raiseHands);
 
     /**
-     * Alias to {@link LivingEntity#isHandRaised()}, if the entity is charging an attack
+     * Alias to {@link LivingEntity#isHandRaised()}, if the entity is charging an attack.
+     *
      * @return If entities hands are raised
      * @deprecated use {@link #isHandRaised()}
      */

paper-api/src/main/java/com/destroystokyo/paper/entity/TargetEntityInfo.java

@@ -2,10 +2,10 @@ package com.destroystokyo.paper.entity;
 
 import org.bukkit.entity.Entity;
 import org.bukkit.util.Vector;
-import org.jetbrains.annotations.NotNull;
 
 /**
- * Represents information about a targeted entity
+ * Represents information about a targeted entity.
+ *
  * @deprecated use {@link org.bukkit.util.RayTraceResult}
  */
 @Deprecated(forRemoval = true, since = "1.19.3")
@@ -13,28 +13,26 @@ public class TargetEntityInfo {
     private final Entity entity;
     private final Vector hitVec;
 
-    public TargetEntityInfo(@NotNull Entity entity, @NotNull Vector hitVec) {
+    public TargetEntityInfo(final Entity entity, final Vector hitVec) {
         this.entity = entity;
         this.hitVec = hitVec;
     }
 
     /**
-     * Get the entity that is targeted
+     * Get the entity that is targeted.
      *
      * @return Targeted entity
      */
-    @NotNull
     public Entity getEntity() {
-        return entity;
+        return this.entity;
     }
 
     /**
-     * Get the position the entity is targeted at
+     * Get the position the entity is targeted at.
      *
      * @return Targeted position
      */
-    @NotNull
     public Vector getHitVector() {
-        return hitVec;
+        return this.hitVec;
     }
 }

paper-api/src/main/java/com/destroystokyo/paper/entity/package-info.java

@@ -0,0 +1,7 @@
+/**
+ * Entity pathfinding, ranged attack and targeting API.
+ */
+@NullMarked
+package com.destroystokyo.paper.entity;
+
+import org.jspecify.annotations.NullMarked;

paper-api/src/main/java/com/destroystokyo/paper/entity/villager/Reputation.java

@@ -3,20 +3,28 @@ package com.destroystokyo.paper.entity.villager;
 import com.google.common.base.Preconditions;
 import java.util.EnumMap;
 import java.util.Map;
-import org.jspecify.annotations.NullMarked;
+import java.util.Set;
+import org.jetbrains.annotations.Unmodifiable;
 
 /**
  * A reputation score for a player on a villager.
  */
-@NullMarked
 public final class Reputation {
 
     private final Map<ReputationType, Integer> reputation;
 
+    /**
+     * Creates an empty reputation.
+     */
     public Reputation() {
         this(new EnumMap<>(ReputationType.class));
     }
 
+    /**
+     * Creates a reputation backed by the given map, so changes to the reputation are made to the map.
+     *
+     * @param reputation the reputation values by type
+     */
     public Reputation(final Map<ReputationType, Integer> reputation) {
         Preconditions.checkArgument(reputation != null, "reputation cannot be null");
         this.reputation = reputation;
@@ -36,7 +44,7 @@ public final class Reputation {
     /**
      * Sets the reputation value for a specific {@link ReputationType}.
      *
-     * @param type The {@link ReputationType type} of reputation to set.
+     * @param type  The {@link ReputationType type} of reputation to set.
      * @param value The value of the {@link ReputationType type}.
      */
     public void setReputation(final ReputationType type, final int value) {
@@ -53,4 +61,13 @@ public final class Reputation {
     public boolean hasReputationSet(final ReputationType type) {
         return this.reputation.containsKey(type);
     }
+
+    /**
+     * Gets a set of all {@link ReputationType types} that have a reputation value set.
+     *
+     * @return A set of {@link ReputationType types}.
+     */
+    public @Unmodifiable Set<ReputationType> getReputationsSet() {
+        return Set.copyOf(this.reputation.keySet());
+    }
 }

paper-api/src/main/java/com/destroystokyo/paper/entity/villager/package-info.java

@@ -0,0 +1,7 @@
+/**
+ * API for villagers.
+ */
+@NullMarked
+package com.destroystokyo.paper.entity.villager;
+
+import org.jspecify.annotations.NullMarked;

paper-api/src/main/java/com/destroystokyo/paper/event/brigadier/AsyncPlayerSendCommandsEvent.java

@@ -7,7 +7,6 @@ import org.bukkit.entity.Player;
 import org.bukkit.event.HandlerList;
 import org.bukkit.event.player.PlayerEvent;
 import org.jetbrains.annotations.ApiStatus;
-import org.jspecify.annotations.NullMarked;
 
 /**
  * Fired any time a Brigadier RootCommandNode is generated for a player to inform the client of commands.
@@ -28,9 +27,10 @@ import org.jspecify.annotations.NullMarked;
  * <p>If your logic is not safe to run asynchronously, only react to the synchronous version.</p>
  *
  * <p>This is a draft/experimental API and is subject to change.</p>
+ *
+ * @param <S> the type of the command source
  */
 @ApiStatus.Experimental
-@NullMarked
 public class AsyncPlayerSendCommandsEvent<S extends CommandSourceStack> extends PlayerEvent {
 
     private static final HandlerList HANDLER_LIST = new HandlerList();

paper-api/src/main/java/com/destroystokyo/paper/event/brigadier/AsyncPlayerSendSuggestionsEvent.java

@@ -7,7 +7,6 @@ import org.bukkit.event.Cancellable;
 import org.bukkit.event.HandlerList;
 import org.bukkit.event.player.PlayerEvent;
 import org.jetbrains.annotations.ApiStatus;
-import org.jspecify.annotations.NullMarked;
 
 /**
  * Called when sending {@link Suggestions} to the client. Will be called asynchronously if a plugin
@@ -16,7 +15,6 @@ import org.jspecify.annotations.NullMarked;
  * <p>
  * If the suggestions are empty after this event has been called, nothing will be sent to the client.
  */
-@NullMarked
 public class AsyncPlayerSendSuggestionsEvent extends PlayerEvent implements Cancellable {
 
     private static final HandlerList HANDLER_LIST = new HandlerList();

paper-api/src/main/java/com/destroystokyo/paper/event/brigadier/CommandRegisteredEvent.java

@@ -1,6 +1,7 @@
 package com.destroystokyo.paper.event.brigadier;
 
 import com.destroystokyo.paper.brigadier.BukkitBrigadierCommand;
+import com.destroystokyo.paper.brigadier.BukkitBrigadierCommandSource;
 import com.mojang.brigadier.tree.ArgumentCommandNode;
 import com.mojang.brigadier.tree.LiteralCommandNode;
 import com.mojang.brigadier.tree.RootCommandNode;
@@ -9,7 +10,7 @@ import org.bukkit.command.Command;
 import org.bukkit.event.Cancellable;
 import org.bukkit.event.HandlerList;
 import org.bukkit.event.server.ServerEvent;
-import org.jetbrains.annotations.NotNull;
+import org.jetbrains.annotations.ApiStatus;
 
 /**
  * Fired anytime the server synchronizes Bukkit commands to Brigadier.
@@ -18,18 +19,19 @@ import org.jetbrains.annotations.NotNull;
  * This is done at Plugin Enable time after commands have been registered, but may also
  * run at a later point in the server lifetime due to plugins, a server reload, etc.</p>
  *
+ * @param <S> the type of the command source
  * @deprecated this event has been superseded by the Commands API and will be removed in a future release.
- * Listen to {@link io.papermc.paper.plugin.lifecycle.event.types.LifecycleEvents#COMMANDS} instead
+ *     Listen to {@link io.papermc.paper.plugin.lifecycle.event.types.LifecycleEvents#COMMANDS} instead
  */
 @Deprecated(since = "1.20.6")
 @Warning(value = true, propagate = false)
-public class CommandRegisteredEvent<S extends com.destroystokyo.paper.brigadier.BukkitBrigadierCommandSource> extends ServerEvent implements Cancellable {
+public class CommandRegisteredEvent<S extends BukkitBrigadierCommandSource> extends ServerEvent implements Cancellable {
 
     private static final HandlerList HANDLER_LIST = new HandlerList();
 
     private final String commandLabel;
     private final Command command;
-    private final com.destroystokyo.paper.brigadier.BukkitBrigadierCommand<S> brigadierCommand;
+    private final BukkitBrigadierCommand<S> brigadierCommand;
     private final RootCommandNode<S> root;
     private final ArgumentCommandNode<S, String> defaultArgs;
     private LiteralCommandNode<S> literal;
@@ -37,7 +39,15 @@ public class CommandRegisteredEvent<S extends com.destroystokyo.paper.brigadier.
 
     private boolean cancelled;
 
-    public CommandRegisteredEvent(String commandLabel, com.destroystokyo.paper.brigadier.BukkitBrigadierCommand<S> brigadierCommand, Command command, RootCommandNode<S> root, LiteralCommandNode<S> literal, ArgumentCommandNode<S, String> defaultArgs) {
+    @ApiStatus.Internal
+    public CommandRegisteredEvent(
+        final String commandLabel,
+        final BukkitBrigadierCommand<S> brigadierCommand,
+        final Command command,
+        final RootCommandNode<S> root,
+        final LiteralCommandNode<S> literal,
+        final ArgumentCommandNode<S, String> defaultArgs
+    ) {
         this.commandLabel = commandLabel;
         this.brigadierCommand = brigadierCommand;
         this.command = command;
@@ -110,15 +120,15 @@ public class CommandRegisteredEvent<S extends com.destroystokyo.paper.brigadier.
      *
      * @param literal new node
      */
-    public void setLiteral(LiteralCommandNode<S> literal) {
+    public void setLiteral(final LiteralCommandNode<S> literal) {
         this.literal = literal;
     }
 
     /**
      * Gets whether this command should is treated as "raw".
      *
-     * @see #setRawCommand(boolean)
      * @return whether this command is treated as "raw"
+     * @see #setRawCommand(boolean)
      */
     public boolean isRawCommand() {
         return this.rawCommand;
@@ -152,16 +162,15 @@ public class CommandRegisteredEvent<S extends com.destroystokyo.paper.brigadier.
      * {@inheritDoc}
      */
     @Override
-    public void setCancelled(boolean cancel) {
+    public void setCancelled(final boolean cancel) {
         this.cancelled = cancel;
     }
 
-    @NotNull
+    @Override
     public HandlerList getHandlers() {
         return HANDLER_LIST;
     }
 
-    @NotNull
     public static HandlerList getHandlerList() {
         return HANDLER_LIST;
     }

paper-api/src/main/java/com/destroystokyo/paper/event/brigadier/package-info.java

@@ -0,0 +1,7 @@
+/**
+ * Events relating to the Brigadier command tree, such as the commands and suggestions sent to clients.
+ */
+@NullMarked
+package com.destroystokyo.paper.event.brigadier;
+
+import org.jspecify.annotations.NullMarked;

paper-api/src/main/java/com/destroystokyo/paper/event/inventory/PrepareGrindstoneEvent.java

@@ -5,11 +5,10 @@ import org.bukkit.inventory.GrindstoneInventory;
 import org.bukkit.inventory.InventoryView;
 import org.bukkit.inventory.ItemStack;
 import org.jetbrains.annotations.ApiStatus;
-import org.jetbrains.annotations.NotNull;
-import org.jetbrains.annotations.Nullable;
+import org.jspecify.annotations.Nullable;
 
 /**
- * Called when an item is put in a slot for grinding in a Grindstone
+ * Called when an item is put in a slot for grinding in a Grindstone.
  *
  * @deprecated use {@link org.bukkit.event.inventory.PrepareGrindstoneEvent}
  */
@@ -18,11 +17,10 @@ import org.jetbrains.annotations.Nullable;
 public class PrepareGrindstoneEvent extends PrepareResultEvent {
 
     @ApiStatus.Internal
-    public PrepareGrindstoneEvent(@NotNull InventoryView inventory, @Nullable ItemStack result) {
+    public PrepareGrindstoneEvent(final InventoryView inventory, final @Nullable ItemStack result) {
         super(inventory, result);
     }
 
-    @NotNull
     @Override
     public GrindstoneInventory getInventory() {
         return (GrindstoneInventory) super.getInventory();

paper-api/src/main/java/com/destroystokyo/paper/event/inventory/PrepareResultEvent.java

@@ -4,13 +4,11 @@ import org.bukkit.event.inventory.PrepareInventoryResultEvent;
 import org.bukkit.inventory.InventoryView;
 import org.bukkit.inventory.ItemStack;
 import org.jetbrains.annotations.ApiStatus;
-import org.jspecify.annotations.NullMarked;
 import org.jspecify.annotations.Nullable;
 
 /**
- * Called when an item is put in an inventory containing a result slot
+ * Called when an item is put in an inventory containing a result slot.
  */
-@NullMarked
 public class PrepareResultEvent extends PrepareInventoryResultEvent {
 
     // HandlerList on PrepareInventoryResultEvent to ensure api compat

paper-api/src/main/java/com/destroystokyo/paper/event/inventory/package-info.java

@@ -0,0 +1,7 @@
+/**
+ * Inventory events.
+ */
+@NullMarked
+package com.destroystokyo.paper.event.inventory;
+
+import org.jspecify.annotations.NullMarked;

paper-api/src/main/java/com/destroystokyo/paper/inventory/meta/ArmorStandMeta.java

@@ -2,75 +2,78 @@ package com.destroystokyo.paper.inventory.meta;
 
 import org.bukkit.inventory.meta.ItemMeta;
 
+/**
+ * Represents the meta of an armor stand item, which controls the armor stand that is spawned from it.
+ */
 public interface ArmorStandMeta extends ItemMeta {
 
     /**
-     * Gets whether the ArmorStand should be invisible when spawned
+     * Gets whether the ArmorStand should be invisible when spawned.
      *
      * @return true if this should be invisible
      */
     boolean isInvisible();
 
     /**
-     * Gets whether this ArmorStand should have no base plate when spawned
+     * Gets whether this ArmorStand should have no base plate when spawned.
      *
      * @return true if it will not have a base plate
      */
     boolean hasNoBasePlate();
 
     /**
-     * Gets whether this ArmorStand should show arms when spawned
+     * Gets whether this ArmorStand should show arms when spawned.
      *
      * @return true if it will show arms
      */
     boolean shouldShowArms();
 
     /**
-     * Gets whether this ArmorStand will be small when spawned
+     * Gets whether this ArmorStand will be small when spawned.
      *
      * @return true if it will be small
      */
     boolean isSmall();
 
     /**
-     * Gets whether this ArmorStand will be a marker when spawned
-     * The exact details of this flag are an implementation detail
+     * Gets whether this ArmorStand will be a marker when spawned.
+     * The exact details of this flag are an implementation detail.
      *
      * @return true if it will be a marker
      */
     boolean isMarker();
 
     /**
-     * Sets that this ArmorStand should be invisible when spawned
+     * Sets that this ArmorStand should be invisible when spawned.
      *
      * @param invisible true if set invisible
      */
     void setInvisible(boolean invisible);
 
     /**
-     * Sets that this ArmorStand should have no base plate when spawned
+     * Sets that this ArmorStand should have no base plate when spawned.
      *
      * @param noBasePlate true if no base plate
      */
     void setNoBasePlate(boolean noBasePlate);
 
     /**
-     * Sets that this ArmorStand should show arms when spawned
+     * Sets that this ArmorStand should show arms when spawned.
      *
      * @param showArms true if show arms
      */
     void setShowArms(boolean showArms);
 
     /**
-     * Sets that this ArmorStand should be small when spawned
+     * Sets that this ArmorStand should be small when spawned.
      *
      * @param small true if small
      */
     void setSmall(boolean small);
 
     /**
-     * Sets that this ArmorStand should be a marker when spawned
-     * The exact details of this flag are an implementation detail
+     * Sets that this ArmorStand should be a marker when spawned.
+     * The exact details of this flag are an implementation detail.
      *
      * @param marker true if a marker
      */

paper-api/src/main/java/com/destroystokyo/paper/inventory/meta/package-info.java

@@ -0,0 +1,7 @@
+/**
+ * Item meta types.
+ */
+@NullMarked
+package com.destroystokyo.paper.inventory.meta;
+
+import org.jspecify.annotations.NullMarked;

paper-api/src/main/java/com/destroystokyo/paper/network/NetworkClient.java

@@ -2,13 +2,11 @@ package com.destroystokyo.paper.network;
 
 import java.net.InetSocketAddress;
 import java.net.SocketAddress;
-import org.jspecify.annotations.NullMarked;
 import org.jspecify.annotations.Nullable;
 
 /**
  * Represents a client connected to the server.
  */
-@NullMarked
 public interface NetworkClient {
 
     /**
@@ -23,7 +21,7 @@ public interface NetworkClient {
      * client's socket address.
      *
      * @return The client's {@link InetSocketAddress}, or the loopback address
-     * if this is a Unix domain socket connection
+     *     if this is a Unix domain socket connection
      */
     InetSocketAddress getAddress();
 

paper-api/src/main/java/com/destroystokyo/paper/network/package-info.java

@@ -0,0 +1,7 @@
+/**
+ * API for clients connecting to the server.
+ */
+@NullMarked
+package com.destroystokyo.paper.network;
+
+import org.jspecify.annotations.NullMarked;

paper-api/src/main/java/com/destroystokyo/paper/profile/PlayerProfile.java

@@ -8,7 +8,6 @@ import net.kyori.adventure.text.object.ObjectContents;
 import net.kyori.adventure.text.object.ObjectContentsLike;
 import net.kyori.adventure.text.object.PlayerHeadObjectContents;
 import org.bukkit.profile.PlayerTextures;
-import org.jspecify.annotations.NullMarked;
 import org.jspecify.annotations.Nullable;
 
 import static net.kyori.adventure.text.object.PlayerHeadObjectContents.property;
@@ -16,40 +15,42 @@ import static net.kyori.adventure.text.object.PlayerHeadObjectContents.property;
 /**
  * Represents a players profile for the game, such as UUID, Name, and textures.
  */
-@NullMarked
 public interface PlayerProfile extends org.bukkit.profile.PlayerProfile, PlayerHeadObjectContents.SkinSource, ObjectContentsLike {
 
     /**
+     * Gets the name of this profile.
+     *
      * @return The players name, if set
      */
     @Override
-    @Nullable
-    String getName();
+    @Nullable String getName();
 
     /**
-     * Sets this profiles Name
+     * Sets this profiles Name.
      *
      * @param name The new Name
      * @return The previous Name
+     * @deprecated create a new profile with {@link org.bukkit.Server#createProfile(UUID, String)} instead
      */
     @Deprecated(forRemoval = true, since = "1.18.1")
-    String setName(@Nullable String name);
+    @Nullable String setName(@Nullable String name);
 
     /**
+     * Gets the unique identifier of this profile.
+     *
      * @return The players unique identifier, if set
      */
-    @Nullable
-    UUID getId();
+    @Nullable UUID getId();
 
     /**
-     * Sets this profiles UUID
+     * Sets this profiles UUID.
      *
      * @param uuid The new UUID
      * @return The previous UUID
+     * @deprecated create a new profile with {@link org.bukkit.Server#createProfile(UUID, String)} instead
      */
     @Deprecated(forRemoval = true, since = "1.18.1")
-    @Nullable
-    UUID setId(@Nullable UUID uuid);
+    @Nullable UUID setId(@Nullable UUID uuid);
 
     /**
      * Gets the {@link PlayerTextures} of this profile.
@@ -65,19 +66,21 @@ public interface PlayerProfile extends org.bukkit.profile.PlayerProfile, PlayerH
      * Copies the given textures.
      *
      * @param textures the textures to copy, or {@code null} to clear the
-     * textures
+     *                 textures
      */
     @Override
     void setTextures(@Nullable PlayerTextures textures);
 
     /**
+     * Gets the properties of this profile.
+     *
      * @return A Mutable set of this player's properties, such as textures.
-     * Values specified here are subject to implementation details.
+     *     Values specified here are subject to implementation details.
      */
     Set<ProfileProperty> getProperties();
 
     /**
-     * Check if the Profile has the specified property
+     * Check if the Profile has the specified property.
      *
      * @param property Property name to check
      * @return If the property is set
@@ -85,7 +88,7 @@ public interface PlayerProfile extends org.bukkit.profile.PlayerProfile, PlayerH
     boolean hasProperty(@Nullable String property);
 
     /**
-     * Sets a property. If the property already exists, the previous one will be replaced
+     * Sets a property. If the property already exists, the previous one will be replaced.
      *
      * @param property Property to set.
      * @throws IllegalArgumentException if setting the property results in more than 16 properties
@@ -93,7 +96,7 @@ public interface PlayerProfile extends org.bukkit.profile.PlayerProfile, PlayerH
     void setProperty(ProfileProperty property);
 
     /**
-     * Sets multiple properties. If any of the set properties already exist, it will be replaced
+     * Sets multiple properties. If any of the set properties already exist, it will be replaced.
      *
      * @param properties The properties to set
      * @throws IllegalArgumentException if the number of properties exceeds 16
@@ -101,7 +104,7 @@ public interface PlayerProfile extends org.bukkit.profile.PlayerProfile, PlayerH
     void setProperties(Collection<ProfileProperty> properties);
 
     /**
-     * Removes a specific property from this profile
+     * Removes a specific property from this profile.
      *
      * @param property The property to remove
      * @return If a property was removed
@@ -109,7 +112,7 @@ public interface PlayerProfile extends org.bukkit.profile.PlayerProfile, PlayerH
     boolean removeProperty(@Nullable String property);
 
     /**
-     * Removes a specific property from this profile
+     * Removes a specific property from this profile.
      *
      * @param property The property to remove
      * @return If a property was removed
@@ -119,7 +122,7 @@ public interface PlayerProfile extends org.bukkit.profile.PlayerProfile, PlayerH
     }
 
     /**
-     * Removes all properties in the collection
+     * Removes all properties in the collection.
      *
      * @param properties The properties to remove
      * @return If any property was removed
@@ -135,11 +138,13 @@ public interface PlayerProfile extends org.bukkit.profile.PlayerProfile, PlayerH
     }
 
     /**
-     * Clears all properties on this profile
+     * Clears all properties on this profile.
      */
     void clearProperties();
 
     /**
+     * Checks whether this profile has both a unique identifier and a name.
+     *
      * @return If the profile is now complete (has UUID and Name)
      */
     @Override
@@ -203,7 +208,7 @@ public interface PlayerProfile extends org.bukkit.profile.PlayerProfile, PlayerH
      * <p>
      * Optionally will also fill textures.
      *
-     * @param textures controls if we should fill the profile with texture properties
+     * @param textures   controls if we should fill the profile with texture properties
      * @param onlineMode Treat this server as online mode or not
      * @return If the profile is now complete (has UUID and Name) (if you get rate limited, this operation may fail)
      */
@@ -216,7 +221,7 @@ public interface PlayerProfile extends org.bukkit.profile.PlayerProfile, PlayerH
      * properties (name, unique id, textures, etc.), and updates existing
      * properties (e.g. name, textures, etc.) to their official and up-to-date
      * values. This operation does not alter the current profile, but produces a
-     * new updated {@link PlayerProfile}.
+     * new updated {@code PlayerProfile}.
      * <p>
      * If no player exists for the unique id or name of this profile, this
      * operation yields a profile that is equal to the current profile, which
@@ -241,7 +246,7 @@ public interface PlayerProfile extends org.bukkit.profile.PlayerProfile, PlayerH
     CompletableFuture<PlayerProfile> update();
 
     /**
-     * Whether this Profile has textures associated to it
+     * Whether this Profile has textures associated to it.
      *
      * @return If it has a textures property
      */
@@ -262,6 +267,7 @@ public interface PlayerProfile extends org.bukkit.profile.PlayerProfile, PlayerH
         return ObjectContents.playerHead(this);
     }
 
+    @SuppressWarnings("UnstableApiUsage")
     @Override
     default void applySkinToPlayerHeadContents(final PlayerHeadObjectContents.Builder builder) {
         if (this.getProperties().isEmpty()) {

paper-api/src/main/java/com/destroystokyo/paper/profile/ProfileProperty.java

@@ -2,23 +2,34 @@ package com.destroystokyo.paper.profile;
 
 import com.google.common.base.Preconditions;
 import java.util.Objects;
-import org.jspecify.annotations.NullMarked;
 import org.jspecify.annotations.Nullable;
 
 /**
- * Represents a property on a {@link PlayerProfile}
+ * Represents a property on a {@link PlayerProfile}.
  */
-@NullMarked
 public final class ProfileProperty {
 
     private final String name;
     private final String value;
     private final @Nullable String signature;
 
+    /**
+     * Creates an unsigned property.
+     *
+     * @param name  the property name
+     * @param value the property value
+     */
     public ProfileProperty(final String name, final String value) {
         this(name, value, null);
     }
 
+    /**
+     * Creates a property.
+     *
+     * @param name      the property name, at most 64 characters
+     * @param value     the property value, at most 32767 characters
+     * @param signature the signature, at most 1024 characters, or {@code null} if unsigned
+     */
     public ProfileProperty(final String name, final String value, final @Nullable String signature) {
         this.name = Preconditions.checkNotNull(name, "ProfileProperty name can not be null");
         this.value = Preconditions.checkNotNull(value, "ProfileProperty value can not be null");
@@ -29,6 +40,8 @@ public final class ProfileProperty {
     }
 
     /**
+     * Gets the name of this property.
+     *
      * @return The property name, ie "textures"
      */
     public String getName() {
@@ -36,6 +49,8 @@ public final class ProfileProperty {
     }
 
     /**
+     * Gets the value of this property.
+     *
      * @return The property value, likely to be base64 encoded
      */
     public String getValue() {
@@ -43,13 +58,17 @@ public final class ProfileProperty {
     }
 
     /**
-     * @return A signature from Mojang for signed properties
+     * Gets the signature of this property.
+     *
+     * @return A signature for signed properties
      */
     public @Nullable String getSignature() {
         return this.signature;
     }
 
     /**
+     * Checks whether this property is signed.
+     *
      * @return If this property has a signature or not
      */
     public boolean isSigned() {

paper-api/src/main/java/com/destroystokyo/paper/profile/package-info.java

@@ -0,0 +1,7 @@
+/**
+ * API for player profiles and their properties.
+ */
+@NullMarked
+package com.destroystokyo.paper.profile;
+
+import org.jspecify.annotations.NullMarked;

paper-api/src/main/java/com/destroystokyo/paper/util/SneakyThrow.java

@@ -1,15 +1,18 @@
 package com.destroystokyo.paper.util;
 
 import org.jetbrains.annotations.ApiStatus;
-import org.jspecify.annotations.NullMarked;
 
 /**
+ * Rethrows checked exceptions without declaring them.
+ *
  * @hidden
  */
 @ApiStatus.Internal
-@NullMarked
 public final class SneakyThrow {
 
+    private SneakyThrow() {
+    }
+
     public static void sneaky(final Throwable exception) {
         SneakyThrow.throwSneaky(exception);
     }

paper-api/src/main/java/com/destroystokyo/paper/util/VersionFetcher.java

@@ -4,13 +4,14 @@ import net.kyori.adventure.text.Component;
 import net.kyori.adventure.text.format.NamedTextColor;
 import org.bukkit.Bukkit;
 import org.jetbrains.annotations.ApiStatus;
-import org.jspecify.annotations.NullMarked;
 
-@NullMarked
+/**
+ * Provides the message shown by the {@code /version} command about whether the server is up to date.
+ */
 public interface VersionFetcher {
 
     /**
-     * Amount of time to cache results for in milliseconds
+     * Amount of time to cache results for in milliseconds.
      * <p>
      * Negative values will never cache.
      *
@@ -36,11 +37,13 @@ public interface VersionFetcher {
      * @deprecated {@code serverVersion} is not required
      */
     @Deprecated
-    default Component getVersionMessage(String serverVersion) {
-        return getVersionMessage();
+    default Component getVersionMessage(final String serverVersion) {
+        return this.getVersionMessage();
     }
 
     /**
+     * A version fetcher used when the server does not provide one.
+     *
      * @hidden
      */
     @ApiStatus.Internal

paper-api/src/main/java/com/destroystokyo/paper/util/package-info.java

@@ -0,0 +1,7 @@
+/**
+ * Miscellaneous Paper utilities.
+ */
+@NullMarked
+package com.destroystokyo.paper.util;
+
+import org.jspecify.annotations.NullMarked;

paper-api/src/main/java/com/destroystokyo/paper/utils/PaperPluginLogger.java

@@ -5,19 +5,25 @@ import java.util.logging.Level;
 import java.util.logging.LogManager;
 import java.util.logging.Logger;
 import org.bukkit.plugin.PluginDescriptionFile;
-import org.jspecify.annotations.NullMarked;
 
 /**
  * Prevents plugins (e.g. Essentials) from changing the parent of the plugin logger.
  */
-@NullMarked
-public class PaperPluginLogger extends Logger {
+public final class PaperPluginLogger extends Logger {
 
     @Deprecated(forRemoval = true)
     public static Logger getLogger(final PluginDescriptionFile description) {
         return getLogger((PluginMeta) description);
     }
 
+    /**
+     * Creates a logger for the given plugin and registers it with the {@link LogManager}.
+     * <p>
+     * If a logger with the same name is already registered, that logger is returned instead.
+     *
+     * @param meta the meta of the plugin to create the logger for
+     * @return the logger for the plugin
+     */
     public static Logger getLogger(final PluginMeta meta) {
         Logger logger = new PaperPluginLogger(meta);
         if (!LogManager.getLogManager().addLogger(logger)) {

paper-api/src/main/java/com/destroystokyo/paper/utils/package-info.java

@@ -0,0 +1,7 @@
+/**
+ * Miscellaneous Paper utilities.
+ */
+@NullMarked
+package com.destroystokyo.paper.utils;
+
+import org.jspecify.annotations.NullMarked;

paper-api/src/main/java/io/papermc/paper/InternalAPIBridge.java

@@ -10,6 +10,7 @@ import io.papermc.paper.plugin.lifecycle.event.LifecycleEventManager;
 import io.papermc.paper.world.damagesource.CombatEntry;
 import io.papermc.paper.world.damagesource.FallLocationType;
 import java.io.IOException;
+import java.util.ServiceLoader;
 import java.util.Set;
 import java.util.function.BooleanSupplier;
 import java.util.function.Function;
@@ -56,10 +57,11 @@ public interface InternalAPIBridge {
      * @return the instance.
      */
     static InternalAPIBridge get() {
+        //<editor-fold defaultstate="collapsed" desc="Holder">
         class Holder {
-
-            public static final InternalAPIBridge INSTANCE = Services.service(InternalAPIBridge.class).orElseThrow();
+            public static final InternalAPIBridge INSTANCE = Services.service(ServiceLoader.load(InternalAPIBridge.class), InternalAPIBridge.class).orElseThrow();
         }
+        //</editor-fold>
 
         return Holder.INSTANCE;
     }

paper-api/src/main/java/io/papermc/paper/ServerBuildInfo.java

@@ -3,6 +3,7 @@ package io.papermc.paper;
 import java.time.Instant;
 import java.util.Optional;
 import java.util.OptionalInt;
+import java.util.ServiceLoader;
 import net.kyori.adventure.key.Key;
 import net.kyori.adventure.util.Services;
 import org.jetbrains.annotations.ApiStatus;
@@ -25,7 +26,7 @@ public interface ServerBuildInfo {
     static ServerBuildInfo buildInfo() {
         //<editor-fold defaultstate="collapsed" desc="Holder">
         final class Holder {
-            static final Optional<ServerBuildInfo> INSTANCE = Services.service(ServerBuildInfo.class);
+            static final Optional<ServerBuildInfo> INSTANCE = Services.service(ServiceLoader.load(ServerBuildInfo.class), ServerBuildInfo.class);
         }
         //</editor-fold>
 

paper-api/src/main/java/io/papermc/paper/advancement/AdvancementDisplay.java

@@ -7,7 +7,6 @@ import net.kyori.adventure.translation.Translatable;
 import net.kyori.adventure.util.Index;
 import org.bukkit.NamespacedKey;
 import org.bukkit.inventory.ItemStack;
-import org.jspecify.annotations.NullMarked;
 import org.jspecify.annotations.Nullable;
 
 /**
@@ -16,7 +15,6 @@ import org.jspecify.annotations.Nullable;
  * The display is used in the chat, in the toast messages and the advancements
  * screen.
  */
-@NullMarked
 public interface AdvancementDisplay {
 
     /**
@@ -65,7 +63,7 @@ public interface AdvancementDisplay {
      *
      * @return {@code true} if a message should be sent
      * @see org.bukkit.event.player.PlayerAdvancementDoneEvent#message() to edit
-     * the message
+     *     the message
      */
     boolean doesAnnounceToChat();
 

paper-api/src/main/java/io/papermc/paper/advancement/package-info.java

@@ -0,0 +1,7 @@
+/**
+ * API for advancements.
+ */
+@NullMarked
+package io.papermc.paper.advancement;
+
+import org.jspecify.annotations.NullMarked;

paper-api/src/main/java/io/papermc/paper/annotation/package-info.java

@@ -0,0 +1,7 @@
+/**
+ * Annotations that describe the API.
+ */
+@NullMarked
+package io.papermc.paper.annotation;
+
+import org.jspecify.annotations.NullMarked;

paper-api/src/main/java/io/papermc/paper/ban/BanListType.java

@@ -3,26 +3,26 @@ package io.papermc.paper.ban;
 import org.bukkit.BanList;
 import org.bukkit.ban.IpBanList;
 import org.bukkit.ban.ProfileBanList;
-import org.jspecify.annotations.NullMarked;
 
 /**
  * Represents a ban-type that a {@link BanList} may track.
  * It enforces the correct return value at compile time.
+ *
+ * @param <T> the type of ban list
  */
-@NullMarked
 public interface BanListType<T> {
 
     /**
-     * Banned IP addresses
+     * Banned IP addresses.
      */
     BanListType<IpBanList> IP = new BanListTypeImpl<>(IpBanList.class);
     /**
-     * Banned player profiles
+     * Banned player profiles.
      */
     BanListType<ProfileBanList> PROFILE = new BanListTypeImpl<>(ProfileBanList.class);
 
     /**
-     * Returns the type class of the ban list used generically
+     * Returns the type class of the ban list used generically.
      *
      * @return the type class
      */

paper-api/src/main/java/io/papermc/paper/ban/BanListTypeImpl.java

@@ -1,9 +1,7 @@
 package io.papermc.paper.ban;
 
 import org.jetbrains.annotations.ApiStatus;
-import org.jspecify.annotations.NullMarked;
 
 @ApiStatus.Internal
-@NullMarked
 record BanListTypeImpl<T>(Class<T> typeClass) implements BanListType<T> {
 }

paper-api/src/main/java/io/papermc/paper/ban/package-info.java

@@ -0,0 +1,7 @@
+/**
+ * Ban list API.
+ */
+@NullMarked
+package io.papermc.paper.ban;
+
+import org.jspecify.annotations.NullMarked;

paper-api/src/main/java/io/papermc/paper/block/fluid/FluidData.java

@@ -4,13 +4,11 @@ import org.bukkit.Fluid;
 import org.bukkit.Location;
 import org.bukkit.util.Vector;
 import org.jetbrains.annotations.Range;
-import org.jspecify.annotations.NullMarked;
 
 /**
  * A representation of a fluid in a specific state of data.
  * This type is not linked to a specific location and hence mostly resembles a {@link org.bukkit.block.data.BlockData}.
  */
-@NullMarked
 public interface FluidData extends Cloneable {
 
     /**
@@ -44,8 +42,7 @@ public interface FluidData extends Cloneable {
      *
      * @return the amount as an integer, between 0 and 8
      */
-    @Range(from = 0, to = 8)
-    int getLevel();
+    @Range(from = 0, to = 8) int getLevel();
 
     /**
      * Computes the height of the fluid in the world.
@@ -57,11 +54,10 @@ public interface FluidData extends Cloneable {
      * @param location the location at which to check the high of this fluid data.
      * @return the height as a float value
      */
-    @Range(from = 0, to = 1)
-    float computeHeight(Location location);
+    @Range(from = 0, to = 1) float computeHeight(Location location);
 
     /**
-     * Returns whether this fluid is a source block
+     * Returns whether this fluid is a source block.
      *
      * @return true if the fluid is a source block, false otherwise
      */

paper-api/src/main/java/io/papermc/paper/block/fluid/package-info.java

@@ -0,0 +1,7 @@
+/**
+ * API for fluids and their data.
+ */
+@NullMarked
+package io.papermc.paper.block.fluid;
+
+import org.jspecify.annotations.NullMarked;

paper-api/src/main/java/io/papermc/paper/block/fluid/type/package-info.java

@@ -0,0 +1,7 @@
+/**
+ * Specific types of {@link io.papermc.paper.block.fluid.FluidData}.
+ */
+@NullMarked
+package io.papermc.paper.block.fluid.type;
+
+import org.jspecify.annotations.NullMarked;

paper-api/src/main/java/io/papermc/paper/brigadier/PaperBrigadier.java

@@ -5,14 +5,13 @@ import io.papermc.paper.command.brigadier.MessageComponentSerializer;
 import net.kyori.adventure.text.Component;
 import net.kyori.adventure.text.ComponentLike;
 import net.kyori.adventure.text.TextComponent;
-import org.checkerframework.checker.nullness.qual.NonNull;
 
 /**
  * Helper methods to bridge the gaps between Brigadier and Paper-MojangAPI.
  *
  * @deprecated for removal. See {@link MessageComponentSerializer} for a direct replacement of functionality found in
- * this class.
- * As a general entrypoint to brigadier on paper, see {@link io.papermc.paper.command.brigadier.Commands}.
+ *     this class.
+ *     As a general entrypoint to brigadier on paper, see {@link io.papermc.paper.command.brigadier.Commands}.
  */
 @Deprecated(forRemoval = true, since = "1.20.6")
 public final class PaperBrigadier {
@@ -28,7 +27,7 @@ public final class PaperBrigadier {
      * @param componentLike The {@link ComponentLike} to use for the {@link Message} contents
      * @return A new Brigadier {@link Message}
      */
-    public static @NonNull Message message(final @NonNull ComponentLike componentLike) {
+    public static Message message(final ComponentLike componentLike) {
         return MessageComponentSerializer.message().serialize(componentLike.asComponent());
     }
 
@@ -42,7 +41,7 @@ public final class PaperBrigadier {
      * @param message The {@link Message} to create a {@link Component} from
      * @return The created {@link Component}
      */
-    public static @NonNull Component componentFromMessage(final @NonNull Message message) {
+    public static Component componentFromMessage(final Message message) {
         return MessageComponentSerializer.message().deserialize(message);
     }
 }

paper-api/src/main/java/io/papermc/paper/brigadier/package-info.java

@@ -0,0 +1,7 @@
+/**
+ * Deprecated helpers for bridging Brigadier and Paper.
+ */
+@NullMarked
+package io.papermc.paper.brigadier;
+
+import org.jspecify.annotations.NullMarked;

paper-api/src/main/java/io/papermc/paper/chat/ChatRenderer.java

@@ -4,22 +4,20 @@ import net.kyori.adventure.audience.Audience;
 import net.kyori.adventure.text.Component;
 import org.bukkit.entity.Player;
 import org.jetbrains.annotations.ApiStatus;
-import org.jspecify.annotations.NullMarked;
 
 /**
  * A chat renderer is responsible for rendering chat messages sent by {@link Player}s to the server.
  */
-@NullMarked
 @FunctionalInterface
 public interface ChatRenderer {
 
     /**
      * Renders a chat message. This will be called once for each receiving {@link Audience}.
      *
-     * @param source the message source
+     * @param source            the message source
      * @param sourceDisplayName the display name of the source player
-     * @param message the chat message
-     * @param viewer the receiving {@link Audience}
+     * @param message           the chat message
+     * @param viewer            the receiving {@link Audience}
      * @return a rendered chat message
      */
     @ApiStatus.OverrideOnly
@@ -59,9 +57,9 @@ public interface ChatRenderer {
         /**
          * Renders a chat message.
          *
-         * @param source the message source
+         * @param source            the message source
          * @param sourceDisplayName the display name of the source player
-         * @param message the chat message
+         * @param message           the chat message
          * @return a rendered chat message
          */
         @ApiStatus.OverrideOnly

paper-api/src/main/java/io/papermc/paper/chat/ViewerUnawareImpl.java

@@ -4,10 +4,8 @@ import net.kyori.adventure.audience.Audience;
 import net.kyori.adventure.text.Component;
 import org.bukkit.entity.Player;
 import org.jetbrains.annotations.ApiStatus;
-import org.jspecify.annotations.NullMarked;
 
 @ApiStatus.Internal
-@NullMarked
 sealed class ViewerUnawareImpl implements ChatRenderer, ChatRenderer.ViewerUnaware permits ViewerUnawareImpl.Default {
     private final ViewerUnaware unaware;
 
@@ -26,7 +24,7 @@ sealed class ViewerUnawareImpl implements ChatRenderer, ChatRenderer.ViewerUnawa
     }
 
     static final class Default extends ViewerUnawareImpl implements ChatRenderer.Default {
-        static final ViewerUnawareImpl.Default INSTANCE = new ViewerUnawareImpl.Default((source, sourceDisplayName, message) -> Component.translatable("chat.type.text", sourceDisplayName, message));
+        static final ViewerUnawareImpl.Default INSTANCE = new ViewerUnawareImpl.Default((_, sourceDisplayName, message) -> Component.translatable("chat.type.text", sourceDisplayName, message));
 
         Default(final ViewerUnaware unaware) {
             super(unaware);

paper-api/src/main/java/io/papermc/paper/chat/package-info.java

@@ -0,0 +1,7 @@
+/**
+ * API for rendering chat messages.
+ */
+@NullMarked
+package io.papermc.paper.chat;
+
+import org.jspecify.annotations.NullMarked;

paper-api/src/main/java/io/papermc/paper/command/CommandBlockHolder.java

@@ -1,10 +1,14 @@
 package io.papermc.paper.command;
 
 import net.kyori.adventure.text.Component;
-import org.jspecify.annotations.NullMarked;
 import org.jspecify.annotations.Nullable;
 
-@NullMarked
+/**
+ * Represents something that holds and runs a command like a command block.
+ *
+ * @see org.bukkit.block.CommandBlock
+ * @see org.bukkit.entity.minecart.CommandMinecart
+ */
 public interface CommandBlockHolder {
 
     /**
@@ -41,17 +45,17 @@ public interface CommandBlockHolder {
 
     /**
      * Gets the success count from this command block.
-     * @see <a href="https://minecraft.wiki/wiki/Command_Block#Success_count">Command_Block#Success_count</a>
      *
      * @return the success count
+     * @see <a href="https://minecraft.wiki/wiki/Command_Block#Success_count">Command_Block#Success_count</a>
      */
     int getSuccessCount();
 
     /**
      * Sets the success count from this command block.
-     * @see <a href="https://minecraft.wiki/wiki/Command_Block#Success_count">Command_Block#Success_count</a>
      *
      * @param successCount the success count
+     * @see <a href="https://minecraft.wiki/wiki/Command_Block#Success_count">Command_Block#Success_count</a>
      */
     void setSuccessCount(int successCount);
 }

paper-api/src/main/java/io/papermc/paper/command/brigadier/argument/position/ColumnBlockPosition.java

@@ -3,13 +3,11 @@ package io.papermc.paper.command.brigadier.argument.position;
 import io.papermc.paper.math.BlockPosition;
 import io.papermc.paper.math.Position;
 import org.jetbrains.annotations.ApiStatus;
-import org.jspecify.annotations.NullMarked;
 
 /**
  * A block position, which does not have a y value.
  */
 @ApiStatus.Experimental
-@NullMarked
 public interface ColumnBlockPosition {
 
     /**

paper-api/src/main/java/io/papermc/paper/command/brigadier/argument/position/ColumnFinePosition.java

@@ -3,13 +3,11 @@ package io.papermc.paper.command.brigadier.argument.position;
 import io.papermc.paper.math.FinePosition;
 import io.papermc.paper.math.Position;
 import org.jetbrains.annotations.ApiStatus;
-import org.jspecify.annotations.NullMarked;
 
 /**
  * A fine position, which does not hold a y value.
  */
 @ApiStatus.Experimental
-@NullMarked
 public interface ColumnFinePosition {
 
     /**

paper-api/src/main/java/io/papermc/paper/command/brigadier/argument/position/package-info.java

@@ -0,0 +1,7 @@
+/**
+ * Positions resolved from Brigadier arguments.
+ */
+@NullMarked
+package io.papermc.paper.command.brigadier.argument.position;
+
+import org.jspecify.annotations.NullMarked;

paper-api/src/main/java/io/papermc/paper/command/brigadier/argument/predicate/BlockInWorldPredicate.java

@@ -54,8 +54,7 @@ public interface BlockInWorldPredicate {
         /**
          * The block passed to the predicate was in an unloaded chunk and the {@code loadChunk} flag was false.
          */
-        UNLOADED_CHUNK,
-        ;
+        UNLOADED_CHUNK;
 
         /**
          * Converts the result into an approximated boolean representation.

paper-api/src/main/java/io/papermc/paper/command/package-info.java

@@ -0,0 +1,7 @@
+/**
+ * Command-related APIs.
+ */
+@NullMarked
+package io.papermc.paper.command;
+
+import org.jspecify.annotations.NullMarked;

paper-api/src/main/java/io/papermc/paper/configuration/package-info.java

@@ -0,0 +1,7 @@
+/**
+ * API for reading selected server configuration settings.
+ */
+@NullMarked
+package io.papermc.paper.configuration;
+
+import org.jspecify.annotations.NullMarked;

paper-api/src/main/java/io/papermc/paper/datacomponent/item/attribute/AttributeModifierDisplay.java

@@ -70,7 +70,7 @@ public interface AttributeModifierDisplay {
     interface OverrideText extends AttributeModifierDisplay {
 
         /**
-         * Overridden text
+         * Overridden text.
          *
          * @return the overridden text
          */

paper-api/src/main/java/io/papermc/paper/datacomponent/item/attribute/AttributeModifierDisplayBridge.java

@@ -3,13 +3,16 @@ package io.papermc.paper.datacomponent.item.attribute;
 import java.util.Optional;
 import java.util.ServiceLoader;
 import net.kyori.adventure.text.ComponentLike;
+import net.kyori.adventure.util.Services;
 
 interface AttributeModifierDisplayBridge {
 
-    Optional<AttributeModifierDisplayBridge> BRIDGE = ServiceLoader.load(AttributeModifierDisplayBridge.class, AttributeModifierDisplayBridge.class.getClassLoader()).findFirst();
-
     static AttributeModifierDisplayBridge bridge() {
-        return BRIDGE.orElseThrow();
+        final class Holder {
+            static final Optional<AttributeModifierDisplayBridge> BRIDGE = Services.service(ServiceLoader.load(AttributeModifierDisplayBridge.class), AttributeModifierDisplayBridge.class);
+        }
+
+        return Holder.BRIDGE.orElseThrow();
     }
 
     AttributeModifierDisplay.Default reset();

paper-api/src/main/java/io/papermc/paper/datacomponent/item/attribute/package-info.java

@@ -1,3 +1,6 @@
+/**
+ * Attribute modifier display API for the {@link io.papermc.paper.datacomponent.DataComponentTypes#ATTRIBUTE_MODIFIERS} data component.
+ */
 @NullMarked
 @MinecraftVersionDependent
 package io.papermc.paper.datacomponent.item.attribute;

paper-api/src/main/java/io/papermc/paper/dialog/Dialog.java

@@ -45,16 +45,22 @@ public interface Dialog extends Keyed, DialogLike {
     }
 
     /**
-     * @deprecated use {@link Registry#getKey(Keyed)}, {@link io.papermc.paper.registry.RegistryAccess#getRegistry(io.papermc.paper.registry.RegistryKey)},
-     * and {@link io.papermc.paper.registry.RegistryKey#DIALOG}. Dialogs can exist without a key.
+     * Gets the key of this dialog.
+     *
+     * @return the key of this dialog
+     * @deprecated use {@link Registry#getKey(Keyed)}, {@link RegistryAccess#getRegistry(RegistryKey)},
+     *     and {@link RegistryKey#DIALOG}. Dialogs can exist without a key.
      */
     @Deprecated(since = "1.21.8", forRemoval = true)
     @Override
     NamespacedKey getKey();
 
     /**
-     * @deprecated use {@link Registry#getKey(Keyed)}, {@link io.papermc.paper.registry.RegistryAccess#getRegistry(io.papermc.paper.registry.RegistryKey)},
-     * and {@link io.papermc.paper.registry.RegistryKey#DIALOG}. Dialogs can exist without a key.
+     * Gets the key of this dialog.
+     *
+     * @return the key of this dialog
+     * @deprecated use {@link Registry#getKey(Keyed)}, {@link RegistryAccess#getRegistry(RegistryKey)},
+     *     and {@link RegistryKey#DIALOG}. Dialogs can exist without a key.
      */
     @Deprecated(since = "1.21.8", forRemoval = true)
     @Override

paper-api/src/main/java/io/papermc/paper/enchantments/EnchantmentRarity.java

@@ -1,6 +1,8 @@
 package io.papermc.paper.enchantments;
 
 /**
+ * Represents the rarity of an enchantment.
+ *
  * @deprecated Enchantments do not have a "rarity" since 1.20.5
  */
 @Deprecated(forRemoval = true, since = "1.20.5")
@@ -13,7 +15,7 @@ public enum EnchantmentRarity {
 
     private final int weight;
 
-    EnchantmentRarity(int weight) {
+    EnchantmentRarity(final int weight) {
         this.weight = weight;
     }
 
@@ -23,6 +25,6 @@ public enum EnchantmentRarity {
      * @return the weight
      */
     public int getWeight() {
-        return weight;
+        return this.weight;
     }
 }

paper-api/src/main/java/io/papermc/paper/enchantments/package-info.java

@@ -0,0 +1,7 @@
+/**
+ * Enchantment API.
+ */
+@NullMarked
+package io.papermc.paper.enchantments;
+
+import org.jspecify.annotations.NullMarked;

paper-api/src/main/java/io/papermc/paper/entity/poi/PoiSearchResult.java

@@ -3,7 +3,6 @@ package io.papermc.paper.entity.poi;
 import java.util.function.Predicate;
 import org.bukkit.Location;
 import org.bukkit.World;
-import org.jspecify.annotations.NullMarked;
 
 /**
  * Holds the result of searching for a point of interest.
@@ -11,7 +10,6 @@ import org.jspecify.annotations.NullMarked;
  * @see World#locateAllPoiInRange(Location, Predicate, int)
  * @see World#locateAllPoiInRange(Location, Predicate, int, PoiType.Occupancy)
  */
-@NullMarked
 public interface PoiSearchResult {
 
     /**

paper-api/src/main/java/io/papermc/paper/entity/poi/PoiType.java

@@ -3,7 +3,6 @@ package io.papermc.paper.entity.poi;
 import io.papermc.paper.InternalAPIBridge;
 import org.bukkit.Keyed;
 import org.bukkit.block.data.BlockData;
-import org.jspecify.annotations.NullMarked;
 
 /**
  * Represents a point of interest (POI).
@@ -14,7 +13,6 @@ import org.jspecify.annotations.NullMarked;
  *
  * @see PoiTypes
  */
-@NullMarked
 public interface PoiType extends Keyed {
 
     /**

paper-api/src/main/java/io/papermc/paper/entity/poi/PoiTypes.java

@@ -3,12 +3,10 @@ package io.papermc.paper.entity.poi;
 import net.kyori.adventure.key.Key;
 import net.kyori.adventure.key.KeyPattern;
 import org.bukkit.Registry;
-import org.jspecify.annotations.NullMarked;
 
 /**
  * All the built-in point of interest types.
  */
-@NullMarked
 public final class PoiTypes {
 
     // Start generate - PoiTypes

paper-api/src/main/java/io/papermc/paper/entity/poi/package-info.java

@@ -0,0 +1,7 @@
+/**
+ * Point of interest (POI) API.
+ */
+@NullMarked
+package io.papermc.paper.entity.poi;
+
+import org.jspecify.annotations.NullMarked;

paper-api/src/main/java/io/papermc/paper/event/connection/PlayerConnectionValidateLoginEvent.java

@@ -46,7 +46,7 @@ public class PlayerConnectionValidateLoginEvent extends Event {
      *
      * @return connection
      * @apiNote disconnecting the player through this connection
-     * or using any methods that may send packets is not supported
+     *     or using any methods that may send packets is not supported
      */
     public PlayerConnection getConnection() {
         return this.connection;
@@ -61,7 +61,7 @@ public class PlayerConnectionValidateLoginEvent extends Event {
     }
 
     /**
-     * Disallows the player from logging in, with the given reason
+     * Disallows the player from logging in, with the given reason.
      *
      * @param message Kick message to display to the user
      */

paper-api/src/main/java/io/papermc/paper/event/executor/EventExecutorFactory.java

@@ -1,10 +1,5 @@
 package io.papermc.paper.event.executor;
 
-import org.bukkit.event.Event;
-import org.bukkit.event.Listener;
-import org.bukkit.plugin.EventExecutor;
-import org.jetbrains.annotations.ApiStatus;
-import org.jspecify.annotations.NullMarked;
 import java.io.IOException;
 import java.io.InputStream;
 import java.lang.constant.ConstantDescs;
@@ -15,16 +10,19 @@ import java.lang.reflect.Method;
 import java.lang.reflect.Modifier;
 import java.util.List;
 import java.util.Objects;
+import org.bukkit.event.Event;
+import org.bukkit.event.Listener;
+import org.bukkit.plugin.EventExecutor;
+import org.jetbrains.annotations.ApiStatus;
 
 @ApiStatus.Internal
-@NullMarked
 public final class EventExecutorFactory {
     private static final byte[] TEMPLATE_CLASS_BYTES;
 
     static {
-        try (final InputStream is = EventExecutorFactory.class.getResourceAsStream("MethodHandleEventExecutorTemplate.class")) {
+        try (InputStream is = EventExecutorFactory.class.getResourceAsStream("MethodHandleEventExecutorTemplate.class")) {
             TEMPLATE_CLASS_BYTES = Objects.requireNonNull(is, "template class is missing").readAllBytes();
-        } catch (IOException e) {
+        } catch (final IOException e) {
             throw new AssertionError(e);
         }
     }
@@ -34,17 +32,19 @@ public final class EventExecutorFactory {
     }
 
     /**
-     * {@return an {@link EventExecutor} implemented by a hidden class calling a method handle}
+     * Creates an {@link EventExecutor} implemented by a hidden class calling a method handle.
      *
      * @param method     the method to be invoked by the created event executor
      * @param eventClass the class of the event to handle
+     * @return the event executor
+     * @throws AssertionError if the hidden class cannot be defined or instantiated
      */
     public static EventExecutor create(final Method method, final Class<? extends Event> eventClass) {
         final List<?> classData = List.of(method, eventClass);
         try {
             final MethodHandles.Lookup newClass = MethodHandles.lookup().defineHiddenClassWithClassData(TEMPLATE_CLASS_BYTES, classData, true);
             return newClass.lookupClass().asSubclass(EventExecutor.class).getDeclaredConstructor().newInstance();
-        } catch (ReflectiveOperationException e) {
+        } catch (final ReflectiveOperationException e) {
             throw new AssertionError(e);
         }
     }
@@ -56,6 +56,10 @@ public final class EventExecutorFactory {
     /**
      * Extracts the class data and creates an adjusted MethodHandle directly usable by the lookup class.
      * The logic is kept here to minimize memory usage per created class.
+     *
+     * @param lookup the lookup of the hidden class, which holds the class data
+     * @return the class data with a method handle adjusted to the event executor signature
+     * @throws AssertionError if the class data cannot be read or the method cannot be unreflected
      */
     static ClassData classData(final MethodHandles.Lookup lookup) {
         try {
@@ -67,7 +71,7 @@ public final class EventExecutorFactory {
             mh = mh.asType(MethodType.methodType(void.class, Listener.class, Event.class));
             final Class<?> eventClass = MethodHandles.classDataAt(lookup, ConstantDescs.DEFAULT_NAME, Class.class, 1);
             return new ClassData(method, mh, eventClass.asSubclass(Event.class));
-        } catch (ReflectiveOperationException e) {
+        } catch (final ReflectiveOperationException e) {
             throw new AssertionError(e);
         }
     }

paper-api/src/main/java/io/papermc/paper/event/executor/MethodHandleEventExecutorTemplate.java

@@ -1,15 +1,14 @@
 package io.papermc.paper.event.executor;
 
 import com.destroystokyo.paper.util.SneakyThrow;
+import java.lang.invoke.MethodHandle;
+import java.lang.invoke.MethodHandles;
+import java.lang.reflect.Method;
 import org.bukkit.event.Event;
 import org.bukkit.event.EventException;
 import org.bukkit.event.Listener;
 import org.bukkit.plugin.EventExecutor;
 import org.jetbrains.annotations.ApiStatus;
-import org.jspecify.annotations.NullMarked;
-import java.lang.invoke.MethodHandle;
-import java.lang.invoke.MethodHandles;
-import java.lang.reflect.Method;
 
 /**
  * This class is designed to be used as hidden class template.
@@ -25,7 +24,6 @@ import java.lang.reflect.Method;
  */
 @SuppressWarnings("unused")
 @ApiStatus.Internal
-@NullMarked
 class MethodHandleEventExecutorTemplate implements EventExecutor {
     private static final Method METHOD;
     private static final MethodHandle HANDLE;
@@ -44,7 +42,7 @@ class MethodHandleEventExecutorTemplate implements EventExecutor {
         if (!EVENT_CLASS.isInstance(event)) return;
         try {
             HANDLE.invokeExact(listener, event);
-        } catch (Throwable t) {
+        } catch (final Throwable t) {
             SneakyThrow.sneaky(t);
         }
     }

paper-api/src/main/java/io/papermc/paper/event/executor/package-info.java

@@ -0,0 +1,9 @@
+/**
+ * Internal implementation of event executors.
+ */
+@NullMarked
+@ApiStatus.Internal
+package io.papermc.paper.event.executor;
+
+import org.jetbrains.annotations.ApiStatus;
+import org.jspecify.annotations.NullMarked;

paper-api/src/main/java/io/papermc/paper/event/inventory/ItemCraftedEvent.java

@@ -5,12 +5,10 @@ import org.bukkit.event.Event;
 import org.bukkit.event.HandlerList;
 import org.bukkit.inventory.ItemStack;
 import org.jetbrains.annotations.ApiStatus;
-import org.jspecify.annotations.NullMarked;
 
 /**
  * Called when a player picks up a crafted item from the result slot of a crafting grid.
  */
-@NullMarked
 public class ItemCraftedEvent extends Event {
 
     private static final HandlerList HANDLER_LIST = new HandlerList();

paper-api/src/main/java/io/papermc/paper/event/inventory/PlayerBundleItemSelectEvent.java

@@ -1,5 +1,6 @@
 package io.papermc.paper.event.inventory;
 
+import java.util.OptionalInt;
 import org.bukkit.entity.Player;
 import org.bukkit.event.HandlerList;
 import org.bukkit.event.inventory.InventoryClickEvent;
@@ -8,15 +9,12 @@ import org.bukkit.inventory.Inventory;
 import org.bukkit.inventory.InventoryView;
 import org.bukkit.inventory.ItemStack;
 import org.jetbrains.annotations.ApiStatus;
-import org.jspecify.annotations.NullMarked;
-import java.util.OptionalInt;
 
 /**
  * Called when a {@link Player} selects an item inside a bundle.
  *
  * @apiNote This event does not fire for bundle item selections in creative mode player inventories.
  */
-@NullMarked
 public final class PlayerBundleItemSelectEvent extends InventoryEvent {
 
     private static final HandlerList HANDLER_LIST = new HandlerList();
@@ -33,7 +31,16 @@ public final class PlayerBundleItemSelectEvent extends InventoryEvent {
     private final Direction direction;
 
     @ApiStatus.Internal
-    public PlayerBundleItemSelectEvent(final InventoryView view, final ItemStack bundle, final int rawSlot, final ItemStack previousItem, final ItemStack selectedItem, final int previousIndex, final int selectedIndex, final Direction direction) {
+    public PlayerBundleItemSelectEvent(
+        final InventoryView view,
+        final ItemStack bundle,
+        final int rawSlot,
+        final ItemStack previousItem,
+        final ItemStack selectedItem,
+        final int previousIndex,
+        final int selectedIndex,
+        final Direction direction
+    ) {
         super(view);
 
         this.bundle = bundle;
@@ -125,9 +132,8 @@ public final class PlayerBundleItemSelectEvent extends InventoryEvent {
     /**
      * Gets the direction from the previous selection to the new one.
      *
-     * @apiNote The direction cannot be reliably determined if there are less than three item stacks inside the bundle, in which case this returns {@link Direction#UNKNOWN}.
-     *
      * @return the direction
+     * @apiNote The direction cannot be reliably determined if there are less than three item stacks inside the bundle, in which case this returns {@link Direction#UNKNOWN}.
      */
     public Direction getDirection() {
         return this.direction;

paper-api/src/main/java/io/papermc/paper/event/inventory/PrepareHopperTransferEvent.java

@@ -6,7 +6,6 @@ import org.bukkit.event.HandlerList;
 import org.bukkit.event.inventory.InventoryMoveItemEvent;
 import org.bukkit.inventory.Inventory;
 import org.jetbrains.annotations.ApiStatus;
-import org.jspecify.annotations.NullMarked;
 
 /**
  * Called when a hopper or hopper minecart is about to choose an item to move,
@@ -15,15 +14,14 @@ import org.jspecify.annotations.NullMarked;
  * The hopper treats disallowed slots of the source as if they do not exist, so
  * a source with items only in disallowed slots is treated as empty.
  */
-@NullMarked
 public class PrepareHopperTransferEvent extends Event {
 
     private static final HandlerList HANDLER_LIST = new HandlerList();
 
+    protected long disallowedSlots;
     private final Inventory source;
     private final Inventory destination;
     private final boolean didSourceInitiate;
-    protected long disallowedSlots;
 
     @ApiStatus.Internal
     public PrepareHopperTransferEvent(final Inventory source, final Inventory destination, final boolean didSourceInitiate) {
@@ -33,7 +31,7 @@ public class PrepareHopperTransferEvent extends Event {
     }
 
     /**
-     * Gets the Inventory that items are being taken from
+     * Gets the Inventory that items are being taken from.
      *
      * @return Inventory that items are being taken from
      */
@@ -42,7 +40,7 @@ public class PrepareHopperTransferEvent extends Event {
     }
 
     /**
-     * Gets the Inventory that items are being put into
+     * Gets the Inventory that items are being put into.
      *
      * @return Inventory that items are being put into
      */
@@ -74,7 +72,7 @@ public class PrepareHopperTransferEvent extends Event {
     /**
      * Sets if the hopper is allowed to take items from a slot of {@link #getSource()}.
      *
-     * @param slot the slot
+     * @param slot    the slot
      * @param allowed whether the slot is allowed
      */
     public void setSlotAllowed(final int slot, final boolean allowed) {

paper-api/src/main/java/io/papermc/paper/event/inventory/package-info.java

@@ -0,0 +1,7 @@
+/**
+ * {@link org.bukkit.event.Event Events} relating to inventories and the items in them.
+ */
+@NullMarked
+package io.papermc.paper.event.inventory;
+
+import org.jspecify.annotations.NullMarked;

paper-api/src/main/java/io/papermc/paper/event/server/AsyncServerDataFixerRemoveBlockEntityEvent.java

@@ -7,7 +7,6 @@ import org.bukkit.Bukkit;
 import org.bukkit.event.Event;
 import org.bukkit.event.HandlerList;
 import org.jetbrains.annotations.ApiStatus;
-import org.jspecify.annotations.NullMarked;
 
 /**
  * This event is emitted by the server when the data fixer is removing a block entity associated with a block
@@ -22,7 +21,6 @@ import org.jspecify.annotations.NullMarked;
  * might be blocking on.
  * Schedule large amount of work into separate thread pools.
  */
-@NullMarked
 public class AsyncServerDataFixerRemoveBlockEntityEvent extends Event {
 
     private static final HandlerList HANDLER_LIST = new HandlerList();
@@ -47,33 +45,40 @@ public class AsyncServerDataFixerRemoveBlockEntityEvent extends Event {
     }
 
     /**
-     * {@return the key representing the no longer existing block entity type}
+     * Returns the key representing the no longer existing block entity type.
+     *
+     * @return the key representing the no longer existing block entity type
      */
     public Key getBlockEntityType() {
-        return blockEntityType;
+        return this.blockEntityType;
     }
 
     /**
-     * {@return the key of the world this block entity was removed from}
+     * Returns the key of the world this block entity was removed from.
      *
+     * @return the key of the world this block entity was removed from
      * @see org.bukkit.Server#getWorld(Key)
      */
     public Key getWorldKey() {
-        return worldKey;
+        return this.worldKey;
     }
 
     /**
-     * {@return the position of the block entity that was removed}
+     * Returns the position of the block entity that was removed.
+     *
+     * @return the position of the block entity that was removed
      */
     public BlockPosition getBlockPosition() {
-        return blockPosition;
+        return this.blockPosition;
     }
 
     /**
-     * {@return an immutable view of the persistent data container that was attached to the removed block entity}
+     * Returns an immutable view of the persistent data container that was attached to the removed block entity.
+     *
+     * @return an immutable view of the persistent data container that was attached to the removed block entity
      */
     public PersistentDataContainerView getPersistentDataContainerView() {
-        return persistentDataContainerView;
+        return this.persistentDataContainerView;
     }
 
     @Override

paper-api/src/main/java/io/papermc/paper/event/server/ServerResourcesReloadedEvent.java

@@ -3,16 +3,17 @@ package io.papermc.paper.event.server;
 import org.bukkit.event.HandlerList;
 import org.bukkit.event.server.ServerEvent;
 import org.jetbrains.annotations.ApiStatus;
-import org.jspecify.annotations.NullMarked;
 
 /**
- * Called when resources such as datapacks are reloaded (e.g. /minecraft:reload)
+ * Called when resources such as datapacks are reloaded (e.g. /minecraft:reload).
  * <p>
  * Intended for use to re-register custom recipes, advancements that may be lost during a reload like this.
  */
-@NullMarked
 public class ServerResourcesReloadedEvent extends ServerEvent {
 
+    /**
+     * The handler list of this event.
+     */
     public static final HandlerList HANDLER_LIST = new HandlerList();
 
     private final Cause cause;
@@ -40,8 +41,17 @@ public class ServerResourcesReloadedEvent extends ServerEvent {
         return HANDLER_LIST;
     }
 
+    /**
+     * The cause of a resource reload.
+     */
     public enum Cause {
+        /**
+         * The resources were reloaded by the {@code /minecraft:reload} command.
+         */
         COMMAND,
+        /**
+         * The resources were reloaded by a plugin.
+         */
         PLUGIN,
     }
 }

paper-api/src/main/java/io/papermc/paper/event/server/WhitelistStateUpdateEvent.java

@@ -7,12 +7,10 @@ import org.bukkit.event.Cancellable;
 import org.bukkit.event.Event;
 import org.bukkit.event.HandlerList;
 import org.jetbrains.annotations.ApiStatus;
-import org.jspecify.annotations.NullMarked;
 
 /**
- * This event gets called when the whitelist status of a player is changed
+ * This event gets called when the whitelist status of a player is changed.
  */
-@NullMarked
 public class WhitelistStateUpdateEvent extends Event implements Cancellable {
 
     private static final HandlerList HANDLER_LIST = new HandlerList();
@@ -29,7 +27,7 @@ public class WhitelistStateUpdateEvent extends Event implements Cancellable {
     }
 
     /**
-     * Gets the player whose whitelist status is being changed
+     * Gets the player whose whitelist status is being changed.
      *
      * @return the player whose status is being changed
      */
@@ -38,7 +36,7 @@ public class WhitelistStateUpdateEvent extends Event implements Cancellable {
     }
 
     /**
-     * Gets the player profile whose whitelist status is being changed
+     * Gets the player profile whose whitelist status is being changed.
      *
      * @return the player profile whose status is being changed
      */
@@ -47,7 +45,7 @@ public class WhitelistStateUpdateEvent extends Event implements Cancellable {
     }
 
     /**
-     * Gets the status change of the player profile
+     * Gets the status change of the player profile.
      *
      * @return the whitelist status
      */
@@ -75,9 +73,16 @@ public class WhitelistStateUpdateEvent extends Event implements Cancellable {
     }
 
     /**
-     * Enum for the whitelist status changes
+     * Enum for the whitelist status changes.
      */
     public enum WhitelistStatus {
-        ADDED, REMOVED
+        /**
+         * The player was added to the whitelist.
+         */
+        ADDED,
+        /**
+         * The player was removed from the whitelist.
+         */
+        REMOVED
     }
 }

paper-api/src/main/java/io/papermc/paper/event/server/package-info.java

@@ -0,0 +1,7 @@
+/**
+ * {@link org.bukkit.event.Event Events} relating to the server.
+ */
+@NullMarked
+package io.papermc.paper.event.server;
+
+import org.jspecify.annotations.NullMarked;

paper-api/src/main/java/io/papermc/paper/event/world/StructuresLocateEvent.java

@@ -12,7 +12,6 @@ import org.bukkit.generator.structure.Structure;
 import org.bukkit.generator.structure.StructureType;
 import org.jetbrains.annotations.ApiStatus;
 import org.jetbrains.annotations.UnmodifiableView;
-import org.jspecify.annotations.NullMarked;
 import org.jspecify.annotations.Nullable;
 
 /**
@@ -28,7 +27,6 @@ import org.jspecify.annotations.Nullable;
  *     <li>{@link World#locateNearestStructure(Location, Structure, int, boolean)} is invoked.</li>
  * </ul>
  */
-@NullMarked
 public class StructuresLocateEvent extends WorldEvent implements Cancellable {
 
     private static final HandlerList HANDLER_LIST = new HandlerList();
@@ -165,6 +163,9 @@ public class StructuresLocateEvent extends WorldEvent implements Cancellable {
 
     /**
      * Result for {@link StructuresLocateEvent}.
+     *
+     * @param pos       the position of the located structure
+     * @param structure the located structure
      */
     public record Result(Position pos, Structure structure) {
 

paper-api/src/main/java/io/papermc/paper/event/world/WorldDifficultyChangeEvent.java

@@ -6,7 +6,6 @@ import org.bukkit.World;
 import org.bukkit.event.HandlerList;
 import org.bukkit.event.world.WorldEvent;
 import org.jetbrains.annotations.ApiStatus;
-import org.jspecify.annotations.NullMarked;
 import org.jspecify.annotations.Nullable;
 
 /**
@@ -15,7 +14,6 @@ import org.jspecify.annotations.Nullable;
  * If the world is in {@link World#isHardcore() hardcore}
  * the resulting difficulty will always be {@link Difficulty#HARD}
  */
-@NullMarked
 public class WorldDifficultyChangeEvent extends WorldEvent {
 
     private static final HandlerList HANDLER_LIST = new HandlerList();

paper-api/src/main/java/io/papermc/paper/event/world/WorldGameRuleChangeEvent.java

@@ -7,20 +7,19 @@ import org.bukkit.event.Cancellable;
 import org.bukkit.event.HandlerList;
 import org.bukkit.event.world.WorldEvent;
 import org.jetbrains.annotations.ApiStatus;
-import org.jspecify.annotations.NullMarked;
 import org.jspecify.annotations.Nullable;
 
 /**
  * Called when a world's gamerule is changed, either by command, world options menu, or by api.
+ *
  * @see <a href="https://minecraft.wiki/w/Game_rule#Modifying_game_rules">Modifying game rules - Minecraft wiki</a>
  */
-@NullMarked
 public class WorldGameRuleChangeEvent extends WorldEvent implements Cancellable {
 
     private static final HandlerList HANDLER_LIST = new HandlerList();
 
-    private final @Nullable CommandSender commandSender;
     protected final GameRule<?> gameRule;
+    private final @Nullable CommandSender commandSender;
     private String value;
     private boolean cancelled;
 

paper-api/src/main/java/io/papermc/paper/event/world/package-info.java

@@ -0,0 +1,7 @@
+/**
+ * {@link org.bukkit.event.Event Events} relating to worlds.
+ */
+@NullMarked
+package io.papermc.paper.event.world;
+
+import org.jspecify.annotations.NullMarked;

paper-api/src/main/java/io/papermc/paper/inventory/ItemRarity.java

@@ -2,9 +2,10 @@ package io.papermc.paper.inventory;
 
 import net.kyori.adventure.text.format.NamedTextColor;
 import net.kyori.adventure.text.format.TextColor;
-import org.jetbrains.annotations.NotNull;
 
 /**
+ * Represents the rarity of an item.
+ *
  * @deprecated use {@link org.bukkit.inventory.ItemRarity} with {@link org.bukkit.inventory.meta.ItemMeta#getRarity()}
  */
 @Deprecated(forRemoval = true, since = "1.20.5")
@@ -15,18 +16,18 @@ public enum ItemRarity {
     RARE(NamedTextColor.AQUA),
     EPIC(NamedTextColor.LIGHT_PURPLE);
 
-    TextColor color;
+    private final TextColor color;
 
-    ItemRarity(TextColor color) {
+    ItemRarity(final TextColor color) {
         this.color = color;
     }
 
     /**
      * Gets the color formatting associated with the rarity.
-     * @return
+     *
+     * @return the color of the rarity
      */
-    @NotNull
     public TextColor getColor() {
-        return color;
+        return this.color;
     }
 }

paper-api/src/main/java/io/papermc/paper/inventory/package-info.java

@@ -0,0 +1,7 @@
+/**
+ * Inventory API.
+ */
+@NullMarked
+package io.papermc.paper.inventory;
+
+import org.jspecify.annotations.NullMarked;

paper-api/src/main/java/io/papermc/paper/inventory/tooltip/TooltipContext.java

@@ -2,13 +2,11 @@ package io.papermc.paper.inventory.tooltip;
 
 import org.bukkit.entity.Player;
 import org.jetbrains.annotations.Contract;
-import org.jspecify.annotations.NullMarked;
 
 /**
  * Context for computing itemstack tooltips via
- * {@link org.bukkit.inventory.ItemStack#computeTooltipLines(TooltipContext, Player)}
+ * {@link org.bukkit.inventory.ItemStack#computeTooltipLines(TooltipContext, Player)}.
  */
-@NullMarked
 public interface TooltipContext {
 
     /**

paper-api/src/main/java/io/papermc/paper/inventory/tooltip/TooltipContextImpl.java

@@ -1,8 +1,6 @@
 package io.papermc.paper.inventory.tooltip;
 
-import org.jspecify.annotations.NullMarked;
 
-@NullMarked
 record TooltipContextImpl(boolean isAdvanced, boolean isCreative) implements TooltipContext {
 
     @Override

paper-api/src/main/java/io/papermc/paper/inventory/tooltip/package-info.java

@@ -0,0 +1,7 @@
+/**
+ * API for item tooltips.
+ */
+@NullMarked
+package io.papermc.paper.inventory.tooltip;
+
+import org.jspecify.annotations.NullMarked;

paper-api/src/main/java/io/papermc/paper/item/MapPostProcessing.java

@@ -1,5 +1,10 @@
 package io.papermc.paper.item;
 
+/**
+ * Post-processing operations that are applied to a filled map when it is crafted.
+ *
+ * @see io.papermc.paper.datacomponent.DataComponentTypes#MAP_POST_PROCESSING
+ */
 public enum MapPostProcessing {
     // Start generate - MapPostProcessing
     LOCK,

paper-api/src/main/java/io/papermc/paper/item/package-info.java

@@ -0,0 +1,7 @@
+/**
+ * Item API.
+ */
+@NullMarked
+package io.papermc.paper.item;
+
+import org.jspecify.annotations.NullMarked;

paper-api/src/main/java/io/papermc/paper/math/Rotation.java

@@ -11,7 +11,7 @@ public interface Rotation {
      * @param pitch the pitch component of the rotation, measured in degrees
      * @return a new {@code Rotation} instance with the specified yaw and pitch
      */
-    static Rotation rotation(float yaw, float pitch) {
+    static Rotation rotation(final float yaw, final float pitch) {
         return new RotationImpl(yaw, pitch);
     }
 

paper-api/src/main/java/io/papermc/paper/persistence/PersistentDataContainerView.java

@@ -1,15 +1,15 @@
 package io.papermc.paper.persistence;
 
+import com.google.common.base.Preconditions;
+import java.io.IOException;
 import java.util.Set;
 import net.kyori.adventure.key.Key;
-import com.google.common.base.Preconditions;
 import org.bukkit.NamespacedKey;
 import org.bukkit.persistence.PersistentDataAdapterContext;
 import org.bukkit.persistence.PersistentDataContainer;
 import org.bukkit.persistence.PersistentDataHolder;
 import org.bukkit.persistence.PersistentDataType;
 import org.jetbrains.annotations.ApiStatus;
-import org.jspecify.annotations.NullMarked;
 import org.jspecify.annotations.Nullable;
 
 /**
@@ -18,7 +18,6 @@ import org.jspecify.annotations.Nullable;
  *
  * @see PersistentDataContainer
  */
-@NullMarked
 @ApiStatus.NonExtendable
 public interface PersistentDataContainerView {
 
@@ -40,14 +39,14 @@ public interface PersistentDataContainerView {
      * tags, like the display name, will not work as the values are stored
      * using your namespace.
      *
-     * @param key the key the value is stored under
+     * @param key  the key the value is stored under
      * @param type the type the primitive stored value has to match
-     * @param <P> the generic type of the stored primitive
-     * @param <C> the generic type of the eventually created complex object
+     * @param <P>  the generic type of the stored primitive
+     * @param <C>  the generic type of the eventually created complex object
      * @return if a value with the provided key and type exists
      * @throws IllegalArgumentException if the key to look up is null
      * @throws IllegalArgumentException if the type to cast the found object to is
-     * null
+     *                                  null
      */
     <P, C> boolean has(NamespacedKey key, PersistentDataType<P, C> type);
 
@@ -98,20 +97,20 @@ public interface PersistentDataContainerView {
      * Returns the metadata value that is stored on the
      * {@link PersistentDataHolder} instance.
      *
-     * @param key the key to look up in the custom tag map
+     * @param key  the key to look up in the custom tag map
      * @param type the type the value must have and will be cast to
-     * @param <P> the generic type of the stored primitive
-     * @param <C> the generic type of the eventually created complex object
+     * @param <P>  the generic type of the stored primitive
+     * @param <C>  the generic type of the eventually created complex object
      * @return the value or {@code null} if no value was mapped under the given
-     * value
+     *     value
      * @throws IllegalArgumentException if the key to look up is null
      * @throws IllegalArgumentException if the type to cast the found object to is
-     * null
+     *                                  null
      * @throws IllegalArgumentException if a value exists under the given key,
-     * but cannot be accessed using the given type
+     *                                  but cannot be accessed using the given type
      * @throws IllegalArgumentException if no suitable adapter was found for
-     * the {@link
-     * PersistentDataType#getPrimitiveType()}
+     *                                  the {@link
+     *                                  PersistentDataType#getPrimitiveType()}
      */
     <P, C> @Nullable C get(NamespacedKey key, PersistentDataType<P, C> type);
 
@@ -120,21 +119,21 @@ public interface PersistentDataContainerView {
      * {@link PersistentDataHolder} instance. If the value does not exist in the
      * container, the default value provided is returned.
      *
-     * @param key the key to look up in the custom tag map
-     * @param type the type the value must have and will be cast to
+     * @param key          the key to look up in the custom tag map
+     * @param type         the type the value must have and will be cast to
      * @param defaultValue the default value to return if no value was found for
-     * the provided key
-     * @param <P> the generic type of the stored primitive
-     * @param <C> the generic type of the eventually created complex object
+     *                     the provided key
+     * @param <P>          the generic type of the stored primitive
+     * @param <C>          the generic type of the eventually created complex object
      * @return the value or the default value if no value was mapped under the
-     * given key
+     *     given key
      * @throws IllegalArgumentException if the key to look up is null
      * @throws IllegalArgumentException if the type to cast the found object to is
-     * null
+     *                                  null
      * @throws IllegalArgumentException if a value exists under the given key,
-     * but cannot be accessed using the given type
+     *                                  but cannot be accessed using the given type
      * @throws IllegalArgumentException if no suitable adapter was found for
-     * the {@link PersistentDataType#getPrimitiveType()}
+     *                                  the {@link PersistentDataType#getPrimitiveType()}
      */
     <P, C> C getOrDefault(NamespacedKey key, PersistentDataType<P, C> type, C defaultValue);
 
@@ -143,14 +142,14 @@ public interface PersistentDataContainerView {
      * {@link PersistentDataHolder} instance.
      *
      * @param dataKey the data key to look up in the custom tag map
-     * @param <C> the generic type of the eventually created complex object
+     * @param <C>     the generic type of the eventually created complex object
      * @return the value or {@code null} if no value was mapped under the given
-     * value
+     *     value
      * @throws IllegalArgumentException if the data key to look up is null
      * @throws IllegalArgumentException if a value exists under the given key,
-     * but cannot be accessed using the given type
+     *                                  but cannot be accessed using the given type
      * @throws IllegalArgumentException if no suitable adapter was found for
-     * the {@link PersistentDataType#getPrimitiveType()}
+     *                                  the {@link PersistentDataType#getPrimitiveType()}
      */
     default <C> @Nullable C get(final PersistentDataKey<C> dataKey) {
         Preconditions.checkArgument(dataKey != null, "The data key cannot be null");
@@ -162,16 +161,16 @@ public interface PersistentDataContainerView {
      * {@link PersistentDataHolder} instance. If the value does not exist in the
      * container, the default value provided is returned.
      *
-     * @param dataKey the data key to look up in the custom tag map
+     * @param dataKey      the data key to look up in the custom tag map
      * @param defaultValue the default value to return if no value was found for
-     * the provided key
-     * @param <C> the generic type of the eventually created complex object
+     *                     the provided key
+     * @param <C>          the generic type of the eventually created complex object
      * @return the value or the default value if no value was mapped under the given key
      * @throws IllegalArgumentException if the data key to look up is null
      * @throws IllegalArgumentException if a value exists under the given key,
-     * but cannot be accessed using the given type
+     *                                  but cannot be accessed using the given type
      * @throws IllegalArgumentException if no suitable adapter was found for
-     * the {@link PersistentDataType#getPrimitiveType()}
+     *                                  the {@link PersistentDataType#getPrimitiveType()}
      */
     default <C> C getOrDefault(final PersistentDataKey<C> dataKey, final C defaultValue) {
         Preconditions.checkArgument(dataKey != null, "The data key cannot be null");
@@ -191,7 +190,7 @@ public interface PersistentDataContainerView {
      *
      * @param key the key to look up the value type of
      * @return estimated data type or null if no value is present, the type is
-     * unknown or an empty list is encountered as value.
+     *     unknown or an empty list is encountered as value.
      */
     @Nullable PersistentDataType<?, ?> getPrimitiveStorageType(Key key);
 
@@ -221,7 +220,7 @@ public interface PersistentDataContainerView {
      * This method only copies custom object keys. Existing tags, like the display
      * name, will not be copied as the values are stored using your namespace.
      *
-     * @param other the container to copy to
+     * @param other   the container to copy to
      * @param replace whether to replace any matching values in the target container
      * @throws IllegalArgumentException if the other container is null
      */
@@ -239,12 +238,14 @@ public interface PersistentDataContainerView {
      * byte array.
      *
      * @return a binary representation of this container
-     * @throws java.io.IOException if we fail to write this container to a byte array
+     * @throws IOException if we fail to write this container to a byte array
      */
-    byte[] serializeToBytes() throws java.io.IOException;
+    byte[] serializeToBytes() throws IOException;
 
     /**
-     * {@return the size of the data container}
+     * Returns the size of the data container.
+     *
+     * @return the size of the data container
      */
     int getSize();
 }

paper-api/src/main/java/io/papermc/paper/persistence/PersistentDataKey.java

@@ -5,7 +5,6 @@ import net.kyori.adventure.key.Key;
 import org.bukkit.NamespacedKey;
 import org.bukkit.persistence.PersistentDataContainer;
 import org.bukkit.persistence.PersistentDataType;
-import org.jspecify.annotations.NullMarked;
 
 /**
  * This class represents the union of a {@link Key} and a
@@ -14,7 +13,7 @@ import org.jspecify.annotations.NullMarked;
  * The advantage of this class is more direct, typed access to data stored in a {@link PersistentDataContainer}.
  * Instead of having to keep track of the {@link NamespacedKey} and {@link PersistentDataType} separately
  * when working with PDC, this class allows you to store both together.
- * <p>
+ *
  * <h2>Example usage</h2>
  * <pre>{@code
  * public class CustomLogic {
@@ -41,16 +40,15 @@ import org.jspecify.annotations.NullMarked;
  *
  * @param <C> the retrieved object type when applying this tag type
  */
-@NullMarked
 public interface PersistentDataKey<C> {
 
     /**
-     * Creates a new {@link PersistentDataKey} with the given {@link Key} and {@link PersistentDataType}.
+     * Creates a new PersistentDataKey with the given {@link Key} and {@link PersistentDataType}.
      *
      * @param key  the access key to store
      * @param type the persistent data type to reference
      * @param <C>  the retrieved object type when applying this tag type
-     * @return a new {@link PersistentDataKey} of the given key and type
+     * @return a new PersistentDataKey of the given key and type
      * @throws IllegalArgumentException if either key or type are null
      */
     static <C> PersistentDataKey<C> of(final Key key, final PersistentDataType<?, C> type) {
@@ -58,12 +56,16 @@ public interface PersistentDataKey<C> {
     }
 
     /**
-     * {@return the access key of this {@link PersistentDataKey}}
+     * Returns the access key of this PersistentDataKey.
+     *
+     * @return the access key of this PersistentDataKey
      */
     NamespacedKey key();
 
     /**
-     * {@return the data type of this {@link PersistentDataKey}}
+     * Returns the data type of this PersistentDataKey.
+     *
+     * @return the data type of this PersistentDataKey
      */
     PersistentDataType<?, C> dataType();
 }

paper-api/src/main/java/io/papermc/paper/persistence/PersistentDataViewHolder.java

@@ -1,13 +1,11 @@
 package io.papermc.paper.persistence;
 
 import org.jetbrains.annotations.ApiStatus;
-import org.jspecify.annotations.NullMarked;
 
 /**
  * The {@link PersistentDataViewHolder} interface defines an object that can view
  * custom persistent data on it.
  */
-@NullMarked
 @ApiStatus.NonExtendable
 public interface PersistentDataViewHolder {
 
@@ -16,7 +14,7 @@ public interface PersistentDataViewHolder {
      * <p>
      * Note that the tags stored on this container are all stored under their
      * own custom namespace therefore modifying default tags using this
-     * {@link PersistentDataViewHolder} is impossible.
+     * PersistentDataViewHolder is impossible.
      *
      * @return the persistent data container view
      */

paper-api/src/main/java/io/papermc/paper/persistence/package-info.java

@@ -0,0 +1,7 @@
+/**
+ * Persistent data container API.
+ */
+@NullMarked
+package io.papermc.paper.persistence;
+
+import org.jspecify.annotations.NullMarked;

paper-api/src/main/java/io/papermc/paper/plugin/PermissionManager.java

@@ -5,7 +5,6 @@ import java.util.Set;
 import org.bukkit.permissions.Permissible;
 import org.bukkit.permissions.Permission;
 import org.jetbrains.annotations.ApiStatus;
-import org.jspecify.annotations.NullMarked;
 import org.jspecify.annotations.Nullable;
 
 /**
@@ -13,11 +12,10 @@ import org.jspecify.annotations.Nullable;
  * the bukkit one before.
  */
 @ApiStatus.Experimental
-@NullMarked
 public interface PermissionManager {
 
     /**
-     * Gets a {@link Permission} from its fully qualified name
+     * Gets a {@link Permission} from its fully qualified name.
      *
      * @param name Name of the permission
      * @return Permission, or null if none
@@ -63,7 +61,7 @@ public interface PermissionManager {
     void removePermission(String name);
 
     /**
-     * Gets the default permissions for the given op status
+     * Gets the default permissions for the given op status.
      *
      * @param op Which set of default permissions to get
      * @return The default permissions
@@ -103,7 +101,7 @@ public interface PermissionManager {
 
     /**
      * Gets a set containing all subscribed {@link Permissible}s to the given
-     * permission, by name
+     * permission, by name.
      *
      * @param permission Permission to query for
      * @return Set containing all subscribed permissions
@@ -111,7 +109,7 @@ public interface PermissionManager {
     Set<Permissible> getPermissionSubscriptions(String permission);
 
     /**
-     * Subscribes to the given Default permissions by operator status
+     * Subscribes to the given Default permissions by operator status.
      * <p>
      * If the specified defaults change in any form, the Permissible will be
      * asked to recalculate.
@@ -122,7 +120,7 @@ public interface PermissionManager {
     void subscribeToDefaultPerms(boolean op, Permissible permissible);
 
     /**
-     * Unsubscribes from the given Default permissions by operator status
+     * Unsubscribes from the given Default permissions by operator status.
      *
      * @param op          Default list to unsubscribe from
      * @param permissible Permissible subscribing
@@ -131,7 +129,7 @@ public interface PermissionManager {
 
     /**
      * Gets a set containing all subscribed {@link Permissible}s to the given
-     * default list, by op status
+     * default list, by op status.
      *
      * @param op Default list to query for
      * @return Set containing all subscribed permissions

paper-api/src/main/java/io/papermc/paper/plugin/bootstrap/BootstrapContext.java

@@ -3,7 +3,6 @@ package io.papermc.paper.plugin.bootstrap;
 import io.papermc.paper.plugin.lifecycle.event.LifecycleEventManager;
 import io.papermc.paper.plugin.lifecycle.event.LifecycleEventOwner;
 import org.jetbrains.annotations.ApiStatus;
-import org.jspecify.annotations.NullMarked;
 
 /**
  * Represents the context provided to a {@link PluginBootstrap} during both the bootstrapping and plugin
@@ -12,13 +11,12 @@ import org.jspecify.annotations.NullMarked;
  * like the plugin's configuration or logger during the plugins bootstrap.
  */
 @ApiStatus.Experimental
-@NullMarked
 @ApiStatus.NonExtendable
 public interface BootstrapContext extends PluginProviderContext, LifecycleEventOwner {
 
     /**
      * Get the lifecycle event manager for registering handlers
-     * for lifecycle events allowed on the {@link BootstrapContext}.
+     * for lifecycle events allowed on the BootstrapContext.
      *
      * @return the lifecycle event manager
      */