Improved documentation for BlockState snapshots and indicated nullability

src/main/java/io/papermc/lib/PaperLib.java

@@ -9,6 +9,7 @@
 import org.bukkit.Location;
 import org.bukkit.World;
 import org.bukkit.block.Block;
+import org.bukkit.block.BlockState;
 import org.bukkit.entity.Entity;
 import org.bukkit.entity.Player;
 import org.bukkit.event.player.PlayerTeleportEvent.TeleportCause;
@@ -180,10 +181,10 @@ public static boolean isChunkGenerated(@Nonnull World world, int x, int z) {
     }
 
     /**
-     * Get's a BlockState, optionally not using a snapshot
-     * @param block The block to get a State of
-     * @param useSnapshot Whether or not to use a snapshot when supported
-     * @return The BlockState
+     * This gets a {@link BlockState}, optionally not using a snapshot (if the {@link Environment} does not override that)
+     * @param block The {@link Block} to get the {@link BlockState} of
+     * @param useSnapshot Whether or not to use a snapshot, may be ignored by certain {@link Environment Environments}
+     * @return The {@link BlockState}
      */
     @Nonnull
     public static BlockStateSnapshotResult getBlockState(@Nonnull Block block, boolean useSnapshot) {

src/main/java/io/papermc/lib/environments/Environment.java

@@ -6,7 +6,7 @@
 import io.papermc.lib.features.asyncteleport.AsyncTeleportSync;
 import io.papermc.lib.features.bedspawnlocation.BedSpawnLocation;
 import io.papermc.lib.features.bedspawnlocation.BedSpawnLocationSync;
-import io.papermc.lib.features.blockstatesnapshot.BlockStateSnapshot;
+import io.papermc.lib.features.blockstatesnapshot.BlockStateSnapshotHandler;
 import io.papermc.lib.features.blockstatesnapshot.BlockStateSnapshotBeforeSnapshots;
 import io.papermc.lib.features.blockstatesnapshot.BlockStateSnapshotNoOption;
 import io.papermc.lib.features.blockstatesnapshot.BlockStateSnapshotResult;
@@ -37,7 +37,7 @@ public abstract class Environment {
     protected AsyncChunks asyncChunksHandler = new AsyncChunksSync();
     protected AsyncTeleport asyncTeleportHandler = new AsyncTeleportSync();
     protected ChunkIsGenerated isGeneratedHandler = new ChunkIsGeneratedUnknown();
-    protected BlockStateSnapshot blockStateSnapshotHandler;
+    protected BlockStateSnapshotHandler blockStateSnapshotHandler;
     protected BedSpawnLocation bedSpawnLocationHandler = new BedSpawnLocationSync();
 
     public Environment() {

src/main/java/io/papermc/lib/features/blockstatesnapshot/BlockStateSnapshotBeforeSnapshots.java

@@ -1,14 +1,18 @@
 package io.papermc.lib.features.blockstatesnapshot;
 
+import javax.annotation.Nonnull;
+
 import org.bukkit.block.Block;
+import org.bukkit.block.BlockState;
 
 /**
- * Block State Snapshots was added in 1.12, this will always be no snapshots
+ * {@link BlockState} Snapshots were added in 1.12, this will always be no snapshots.
  */
-public class BlockStateSnapshotBeforeSnapshots implements BlockStateSnapshot {
+public class BlockStateSnapshotBeforeSnapshots implements BlockStateSnapshotHandler {
 
     @Override
-    public BlockStateSnapshotResult getBlockState(Block block, boolean useSnapshot) {
+    @Nonnull
+    public BlockStateSnapshotResult getBlockState(@Nonnull Block block, boolean useSnapshot) {
         return new BlockStateSnapshotResult(false, block.getState());
     }
 }

src/main/java/io/papermc/lib/features/blockstatesnapshot/BlockStateSnapshotHandler.java

@@ -0,0 +1,34 @@
+package io.papermc.lib.features.blockstatesnapshot;
+
+import javax.annotation.Nonnull;
+
+import org.bukkit.block.Block;
+import org.bukkit.block.BlockState;
+
+import io.papermc.lib.environments.Environment;
+
+/**
+ * A {@link BlockStateSnapshotHandler} is responsible for getting a {@link BlockState}
+ * from a {@link Block}. This {@link BlockState} can be a snapshot or not, which depends
+ * on the Server software that is used or the arguments that are passed.
+ * <br>
+ * You can use {@link #getBlockState(Block, boolean)} to the actual {@link BlockStateSnapshotResult}
+ * that holds the {@link BlockState} and a boolean determining whether it was a snapshot or not.
+ *
+ */
+@FunctionalInterface
+public interface BlockStateSnapshotHandler {
+
+    /**
+     * This takes the {@link BlockState} of a given {@link Block}, optionally as a snapshot.
+     * The {@link Environment} may override this behaviour to always use snapshots or to always
+     * use non-snapshots.
+     * 
+     * @param block The {@link Block} to get the {@link BlockState} from
+     * @param useSnapshot Whether a snapshot should be taken, might be overridden in certain {@link Environment Environments}
+     * @return A {@link BlockStateSnapshotResult}
+     */
+    @Nonnull
+    BlockStateSnapshotResult getBlockState(@Nonnull Block block, boolean useSnapshot);
+
+}

src/main/java/io/papermc/lib/features/blockstatesnapshot/BlockStateSnapshotNoOption.java

@@ -1,10 +1,22 @@
 package io.papermc.lib.features.blockstatesnapshot;
 
+import javax.annotation.Nonnull;
+
 import org.bukkit.block.Block;
+import org.bukkit.block.BlockState;
+
+import io.papermc.lib.environments.Environment;
+
+/**
+ * This {@link BlockStateSnapshotHandler} is used when the {@link Environment} forces every
+ * {@link BlockState} to be a snaphot.
+ *
+ */
+public class BlockStateSnapshotNoOption implements BlockStateSnapshotHandler {
 
-public class BlockStateSnapshotNoOption implements BlockStateSnapshot {
     @Override
-    public BlockStateSnapshotResult getBlockState(Block block, boolean useSnapshot) {
+    @Nonnull
+    public BlockStateSnapshotResult getBlockState(@Nonnull Block block, boolean useSnapshot) {
         return new BlockStateSnapshotResult(true, block.getState());
     }
 }

src/main/java/io/papermc/lib/features/blockstatesnapshot/BlockStateSnapshotOptionalSnapshots.java

@@ -1,10 +1,22 @@
 package io.papermc.lib.features.blockstatesnapshot;
 
+import javax.annotation.Nonnull;
+
 import org.bukkit.block.Block;
 
-public class BlockStateSnapshotOptionalSnapshots implements BlockStateSnapshot {
+import io.papermc.lib.environments.Environment;
+
+/**
+ * This {@link BlockStateSnapshotHandler} allows the developer to decide whether or not to
+ * take a snapshot.
+ * if this handler is used, then the {@link Environment} supports both snapshots and non-snapshots.
+ *
+ */
+public class BlockStateSnapshotOptionalSnapshots implements BlockStateSnapshotHandler {
+
     @Override
-    public BlockStateSnapshotResult getBlockState(Block block, boolean useSnapshot) {
+    @Nonnull
+    public BlockStateSnapshotResult getBlockState(@Nonnull Block block, boolean useSnapshot) {
         return new BlockStateSnapshotResult(useSnapshot, block.getState(useSnapshot));
     }
 }

src/main/java/io/papermc/lib/features/blockstatesnapshot/BlockStateSnapshotResult.java

@@ -1,20 +1,54 @@
 package io.papermc.lib.features.blockstatesnapshot;
 
+import javax.annotation.Nonnull;
+
+import org.bukkit.block.Block;
 import org.bukkit.block.BlockState;
 
+import io.papermc.lib.PaperLib;
+import io.papermc.lib.environments.Environment;
+
+/**
+ * Objects of this type are the result of {@link PaperLib#getBlockState(Block, boolean)}.
+ * You can use a {@link BlockStateSnapshotResult} to obtain the actual {@link BlockState} but
+ * also to determine whether a snapshot was taken or not.
+ *
+ */
 public class BlockStateSnapshotResult {
+
     private final boolean isSnapshot;
     private final BlockState state;
 
-    public BlockStateSnapshotResult(boolean isSnapshot, BlockState state) {
+    /**
+     * This creates a new {@link BlockStateSnapshotResult} with the given arguments.
+     * This constructor is normally invoked by a {@link BlockStateSnapshotHandler}.
+     * 
+     * @param isSnapshot Whether this {@link BlockState} is a snapshot or not
+     * @param state The corresponding {@link BlockState}
+     */
+    public BlockStateSnapshotResult(boolean isSnapshot, @Nonnull BlockState state) {
         this.isSnapshot = isSnapshot;
         this.state = state;
     }
 
+    /**
+     * This method returns whether the corresponding {@link BlockState} is a snapshot or not.
+     * A {@link BlockState} will be a snapshot if explicitly requested or if the {@link Environment}
+     * does not allow non-snapshot {@link BlockState BlockStates}.
+     * 
+     * @return Whether this {@link BlockState} is a snapshot
+     */
     public boolean isSnapshot() {
         return isSnapshot;
     }
 
+    /**
+     * This returns the {@link BlockState} that was taken.
+     * To check if it is a snapshot, see {@link #isSnapshot()}.
+     * 
+     * @return The taken {@link BlockState}
+     */
+    @Nonnull
     public BlockState getState() {
         return state;
     }