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/features/blockstatesnapshot/BlockStateSnapshot.java

@@ -1,7 +1,32 @@
 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 BlockStateSnapshot} 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.
+ * <p>
+ * 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.
+ */
 public interface BlockStateSnapshot {
- BlockStateSnapshotResult getBlockState(Block block, boolean useSnapshot);
+
+ /**
+ * 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/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 {
 
  @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/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 BlockStateSnapshot} is used when the {@link Environment} forces every
+ * {@link BlockState} to be a snaphot.
+ *
+ */
 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,21 @@
 package io.papermc.lib.features.blockstatesnapshot;
 
+import javax.annotation.Nonnull;
+
 import org.bukkit.block.Block;
 
+import io.papermc.lib.environments.Environment;
+
+/**
+ * This {@link BlockStateSnapshot} 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 BlockStateSnapshot {
+
  @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,53 @@
 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 BlockStateSnapshot}.
+ * 
+ * @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}s.
+ * 
+ * @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 captured {@link BlockState}.
+ */
+ @Nonnull
  public BlockState getState() {
  return state;
  }