docs: Add @since annotation for v6 changes (#3471)

Bukkit/src/main/java/com/plotsquared/bukkit/managers/MultiverseWorldManager.java

@@ -38,7 +38,7 @@ import org.checkerframework.checker.nullness.qual.Nullable;
  * @deprecated Deprecated and scheduled for removal without replacement
  *         in favor of the build in setup wizard.
  */
-@Deprecated(forRemoval = true)
+@Deprecated(forRemoval = true, since = "6.0.0")
 @Singleton
 public class MultiverseWorldManager extends BukkitWorldManager {
 

Core/src/main/java/com/plotsquared/core/PlotPlatform.java

@@ -274,6 +274,7 @@ public interface PlotPlatform<P> extends LocaleHolder {
      * Get the {@link PlotAreaManager} implementation.
      *
      * @return the PlotAreaManager
+     * @since 6.1.4
      */
     @NonNull PlotAreaManager plotAreaManager();
 

Core/src/main/java/com/plotsquared/core/command/Chat.java

@@ -34,7 +34,7 @@ import net.kyori.adventure.text.minimessage.Template;
  * @deprecated In favor of "/plot toggle chat" and
  *         scheduled for removal within the next major release.
  */
-@Deprecated(forRemoval = true)
+@Deprecated(forRemoval = true, since = "6.0.0")
 @CommandDeclaration(command = "chat",
         usage = "/plot chat",
         permission = "plots.chat",

Core/src/main/java/com/plotsquared/core/command/Save.java

@@ -50,7 +50,7 @@ import java.util.UUID;
  * @deprecated In favor of "/plot download" (Arkitektonika) and scheduled
  *         for removal within the next major release.
  */
-@Deprecated(forRemoval = true)
+@Deprecated(forRemoval = true, since = "6.0.9")
 @CommandDeclaration(command = "save",
         category = CommandCategory.SCHEMATIC,
         requiredType = RequiredType.NONE,

Core/src/main/java/com/plotsquared/core/configuration/Settings.java

@@ -438,7 +438,7 @@ public class Settings extends Config {
     }
 
 
-    @Deprecated(forRemoval = true)
+    @Deprecated(forRemoval = true, since = "6.0.0")
     @Comment("Schematic interface related settings")
     public static class Web {
 

Core/src/main/java/com/plotsquared/core/configuration/caption/CaptionUtility.java

@@ -103,6 +103,7 @@ public class CaptionUtility {
      * @param miniMessageString the message from which the specified click events should be removed from.
      * @return the string without the click events that are configured to be removed.
      * @see Settings.Chat#CLICK_EVENT_ACTIONS_TO_REMOVE
+     * @since 6.0.10
      */
     public static String stripClickEvents(final @NonNull String miniMessageString) {
         // parse, transform and serialize again
@@ -122,6 +123,7 @@ public class CaptionUtility {
      * @return the string without the click events that are configured to be removed.
      * @see Settings.Chat#CLICK_EVENT_ACTIONS_TO_REMOVE
      * @see #stripClickEvents(String)
+     * @since 6.0.10
      */
     public static String stripClickEvents(
             final @NonNull PlotFlag<?, ?> flag,

Core/src/main/java/com/plotsquared/core/configuration/caption/ComponentTransform.java

@@ -39,6 +39,7 @@ public interface ComponentTransform {
      *
      * @param transform the transform to apply.
      * @return a new transform which is applied on all child components and the component itself.
+     * @since 6.0.10
      */
     static ComponentTransform nested(ComponentTransform transform) {
         return new NestedComponentTransform(transform);
@@ -51,6 +52,7 @@ public interface ComponentTransform {
      *
      * @param actionsToRemove the actions used to filter which click events should be removed.
      * @return a new transform that removes click events from a component.
+     * @since 6.0.10
      */
     static ComponentTransform stripClicks(ClickEvent.Action... actionsToRemove) {
         return new ClickStripTransform(Set.of(actionsToRemove));
@@ -61,6 +63,7 @@ public interface ComponentTransform {
      *
      * @param original the component to transform.
      * @return the transformed component.
+     * @since 6.0.10
      */
     @NonNull Component transform(@NonNull Component original);
 

Core/src/main/java/com/plotsquared/core/events/PlayerAutoPlotEvent.java

@@ -115,7 +115,7 @@ public class PlayerAutoPlotEvent extends PlotEvent implements CancellablePlotEve
     /**
      * @deprecated for removal. Use {@link PlayerAutoPlotEvent#getSizeX()}
      */
-    @Deprecated(forRemoval = true)
+    @Deprecated(forRemoval = true, since = "6.1.0")
     public int getSize_x() {
         return getSizeX();
     }
@@ -123,7 +123,7 @@ public class PlayerAutoPlotEvent extends PlotEvent implements CancellablePlotEve
     /**
      * @deprecated for removal. Use {@link PlayerAutoPlotEvent#setSizeX(int)} )}
      */
-    @Deprecated(forRemoval = true)
+    @Deprecated(forRemoval = true, since = "6.1.0")
     public void setSize_x(int sizeX) {
         setSizeX(sizeX);
     }
@@ -131,7 +131,7 @@ public class PlayerAutoPlotEvent extends PlotEvent implements CancellablePlotEve
     /**
      * @deprecated for removal. Use {@link PlayerAutoPlotEvent#getSizeZ()}
      */
-    @Deprecated(forRemoval = true)
+    @Deprecated(forRemoval = true, since = "6.1.0")
     public int getSize_z() {
         return getSizeZ();
     }
@@ -139,7 +139,7 @@ public class PlayerAutoPlotEvent extends PlotEvent implements CancellablePlotEve
     /**
      * @deprecated for removal. Use {@link PlayerAutoPlotEvent#setSizeZ(int)} )}
      */
-    @Deprecated(forRemoval = true)
+    @Deprecated(forRemoval = true, since = "6.1.0")
     public void setSize_z(int sizeZ) {
         setSizeZ(sizeZ);
     }
@@ -148,6 +148,7 @@ public class PlayerAutoPlotEvent extends PlotEvent implements CancellablePlotEve
      * Get the x size of the auto-area
      *
      * @return x size
+     * @since 6.1.0
      */
     public int getSizeX() {
         return this.sizeX;
@@ -157,6 +158,7 @@ public class PlayerAutoPlotEvent extends PlotEvent implements CancellablePlotEve
      * Set the x size of the auto-area
      *
      * @param sizeX x size
+     * @since 6.1.0
      */
     public void setSizeX(int sizeX) {
         this.sizeX = sizeX;
@@ -166,6 +168,7 @@ public class PlayerAutoPlotEvent extends PlotEvent implements CancellablePlotEve
      * Get the z size of the auto-area
      *
      * @return z size
+     * @since 6.1.0
      */
     public int getSizeZ() {
         return this.sizeZ;
@@ -175,6 +178,7 @@ public class PlayerAutoPlotEvent extends PlotEvent implements CancellablePlotEve
      * Set the z size of the auto-area
      *
      * @param sizeZ z size
+     * @since 6.1.0
      */
     public void setSizeZ(int sizeZ) {
         this.sizeZ = sizeZ;

Core/src/main/java/com/plotsquared/core/events/PlayerAutoPlotsChosenEvent.java

@@ -47,6 +47,7 @@ public class PlayerAutoPlotsChosenEvent extends PlotPlayerEvent {
      *
      * @param player Player that executed the auto
      * @param plots  Plots that have been chosen to be set to the player
+     * @since 6.1.0
      */
     public PlayerAutoPlotsChosenEvent(PlotPlayer<?> player, List<Plot> plots) {
         super(player, plots.size() > 0 ? plots.get(0) : null);
@@ -67,6 +68,7 @@ public class PlayerAutoPlotsChosenEvent extends PlotPlayerEvent {
      * Get the immutable list of plots selected to be claimed by the player. May be of length 0.
      *
      * @return immutable list.
+     * @since 6.1.0
      */
     public @NonNull List<Plot> getPlots() {
         return plots;
@@ -76,6 +78,7 @@ public class PlayerAutoPlotsChosenEvent extends PlotPlayerEvent {
      * Set the plots to be claimed by the player.
      *
      * @param plots list of plots.
+     * @since 6.1.0
      */
     public void setPlots(final @NonNull List<Plot> plots) {
         this.plots = List.copyOf(plots);

Core/src/main/java/com/plotsquared/core/events/PlayerTeleportToPlotEvent.java

@@ -42,7 +42,7 @@ public class PlayerTeleportToPlotEvent extends PlotPlayerEvent implements Cancel
      * @deprecated use {@link PlayerTeleportToPlotEvent#PlayerTeleportToPlotEvent(PlotPlayer, Location, Plot, TeleportCause)}.
      * You should not be creating events in the first place.
      */
-    @Deprecated(forRemoval = true)
+    @Deprecated(forRemoval = true, since = "6.1.0")
     public PlayerTeleportToPlotEvent(PlotPlayer<?> player, Location from, Plot plot) {
         this(player, from, plot, TeleportCause.UNKNOWN);
     }
@@ -54,6 +54,7 @@ public class PlayerTeleportToPlotEvent extends PlotPlayerEvent implements Cancel
      * @param from   Start location
      * @param plot   Plot to which the player was teleported
      * @param cause  Why the teleport is being completed
+     * @since 6.1.0
      */
     public PlayerTeleportToPlotEvent(PlotPlayer<?> player, Location from, Plot plot, TeleportCause cause) {
         super(player, plot);
@@ -65,6 +66,7 @@ public class PlayerTeleportToPlotEvent extends PlotPlayerEvent implements Cancel
      * Get the teleport cause
      *
      * @return TeleportCause
+     * @since 6.1.0
      */
     public TeleportCause getCause() {
         return cause;

Core/src/main/java/com/plotsquared/core/events/PlotClaimedNotifyEvent.java

@@ -39,6 +39,7 @@ public class PlotClaimedNotifyEvent extends PlotEvent {
      *
      * @param plot Plot that was claimed
      * @param auto If the plot was claimed using /plot auto
+     * @since 6.1.0
      */
     public PlotClaimedNotifyEvent(Plot plot, boolean auto) {
         super(plot);
@@ -49,7 +50,9 @@ public class PlotClaimedNotifyEvent extends PlotEvent {
      * If the plot was claimed using /plot auto
      *
      * @return if claimed with auto
+     * @since 6.1.0
      */
+    @SuppressWarnings("unused")
     public boolean wasAuto() {
         return auto;
     }

Core/src/main/java/com/plotsquared/core/events/TeleportCause.java

@@ -57,12 +57,16 @@ public enum TeleportCause {
     PLUGIN,
     UNKNOWN;
 
+    /**
+     * @since 6.1.0
+     */
     public static final class CauseSets {
 
         public static final Set<TeleportCause> COMMAND = Sets.immutableEnumSet(EnumSet.range(
                 TeleportCause.COMMAND,
                 TeleportCause.COMMAND_VISIT
         ));
+        @SuppressWarnings("unused")
         public static final Set<TeleportCause> PLUGIN = Sets.immutableEnumSet(EnumSet.range(
                 TeleportCause.DEATH,
                 TeleportCause.PLUGIN

Core/src/main/java/com/plotsquared/core/permissions/PermissionHolder.java

@@ -52,6 +52,7 @@ public interface PermissionHolder {
      * @param permission Permission
      * @param key        Permission "key"
      * @return {@code true} if the owner has the given permission, else {@code false}
+     * @since 6.0.10
      */
     default boolean hasKeyedPermission(
             final @NonNull String permission,
@@ -115,6 +116,7 @@ public interface PermissionHolder {
      * @param permission Permission
      * @param key        Permission "key"
      * @return {@code true} if the owner has the given permission, else {@code false}
+     * @since 6.0.10
      */
     boolean hasKeyedPermission(@Nullable String world, @NonNull String permission, @NonNull String key);
 

Core/src/main/java/com/plotsquared/core/permissions/PermissionProfile.java

@@ -59,7 +59,9 @@ public interface PermissionProfile {
      * @param permission Permission
      * @param key        Permission "key"
      * @return {@code true} if the owner has the given permission, else {@code false}
+     * @since 6.0.10
      */
+    @SuppressWarnings("unused")
     default boolean hasKeyedPermission(
             final @NonNull String permission,
             final @NonNull String key
@@ -75,6 +77,7 @@ public interface PermissionProfile {
      * @param permission Permission
      * @param key        Permission "key"
      * @return {@code true} if the owner has the given permission, else {@code false}
+     * @since 6.0.10
      */
     boolean hasKeyedPermission(
             @Nullable String world, final @NonNull String permission,

Core/src/main/java/com/plotsquared/core/plot/Plot.java

@@ -1698,7 +1698,7 @@ public class Plot {
         return base.settings != null && base.settings.getRatings() != null;
     }
 
-    @Deprecated(forRemoval = true)
+    @Deprecated(forRemoval = true, since = "6.1.0")
     public boolean claim(final @NonNull PlotPlayer<?> player, boolean teleport, String schematic) {
         if (!canClaim(player)) {
             return false;
@@ -1706,7 +1706,7 @@ public class Plot {
         return claim(player, teleport, schematic, true);
     }
 
-    @Deprecated(forRemoval = true)
+    @Deprecated(forRemoval = true, since = "6.1.0")
     public boolean claim(final @NonNull PlotPlayer<?> player, boolean teleport, String schematic, boolean updateDB) {
         return claim(player, teleport, schematic, updateDB, false);
     }
@@ -1720,6 +1720,7 @@ public class Plot {
      * @param updateDB  If the database should be updated
      * @param auto      If the plot is being claimed by a /plot auto
      * @return success
+     * @since 6.1.0
      */
     public boolean claim(
             final @NonNull PlotPlayer<?> player, boolean teleport, String schematic, boolean updateDB,

Core/src/main/java/com/plotsquared/core/plot/PlotArea.java

@@ -1276,8 +1276,9 @@ public abstract class PlotArea {
      * @deprecated Use {@link #signMaterial()}. This method is used for 1.13 only and
      *         will be removed without replacement in favor of {@link #signMaterial()}
      *         once we remove the support for 1.13.
+     * @since 6.0.3
      */
-    @Deprecated(forRemoval = true)
+    @Deprecated(forRemoval = true, since = "6.0.3")
     public String getLegacySignMaterial() {
         return this.legacySignMaterial;
     }
@@ -1323,14 +1324,18 @@ public abstract class PlotArea {
 
     /**
      * Get the location for non-members to be teleported to.
+     *
+     * @since 6.1.4
      */
     public BlockLoc nonmemberHome() {
         return this.nonmemberHome;
     }
 
     /**
-     * Get the default location for players to be teleported to. May be overriden by {@link #nonmemberHome} if the player is
+     * Get the default location for players to be teleported to. May be overridden by {@link #nonmemberHome} if the player is
      * not a member of the plot.
+     *
+     * @since 6.1.4
      */
     public BlockLoc defaultHome() {
         return this.defaultHome;
@@ -1339,7 +1344,7 @@ public abstract class PlotArea {
     /**
      * @deprecated Use {@link #nonmemberHome}
      */
-    @Deprecated(forRemoval = true)
+    @Deprecated(forRemoval = true, since = "6.1.4")
     public PlotLoc getNonmemberHome() {
         return new PlotLoc(this.defaultHome.getX(), this.defaultHome.getY(), this.defaultHome.getZ());
     }
@@ -1347,7 +1352,7 @@ public abstract class PlotArea {
     /**
      * @deprecated Use {@link #defaultHome}
      */
-    @Deprecated(forRemoval = true)
+    @Deprecated(forRemoval = true, since = "6.1.4")
     public PlotLoc getDefaultHome() {
         return new PlotLoc(this.defaultHome.getX(), this.defaultHome.getY(), this.defaultHome.getZ());
     }

Core/src/main/java/com/plotsquared/core/plot/PlotManager.java

@@ -214,7 +214,7 @@ public abstract class PlotManager {
      * @return the world height
      * @deprecated In favor of custom world heights within 1.17 and therefore scheduled for removal without replacement
      */
-    @Deprecated(forRemoval = true)
+    @Deprecated(forRemoval = true, since = "6.0.0")
     public int getWorldHeight() {
         return 255;
     }

Core/src/main/java/com/plotsquared/core/plot/PlotTitle.java

@@ -30,6 +30,9 @@ import java.util.Objects;
 
 public class PlotTitle {
 
+    /**
+     * @since 6.1.0
+     */
     public static final PlotTitle CONFIGURED = new PlotTitle();
 
     private final String title;
@@ -40,6 +43,9 @@ public class PlotTitle {
         subtitle = null;
     }
 
+    /**
+     * @since 6.0.10
+     */
     public PlotTitle(String title, String subtitle) {
         Objects.requireNonNull(title);
         Objects.requireNonNull(subtitle);
@@ -47,11 +53,17 @@ public class PlotTitle {
         this.subtitle = subtitle;
     }
 
+    /**
+     * @since 6.0.10
+     */
     @Nullable
     public String title() {
         return title;
     }
 
+    /**
+     * @since 6.0.10
+     */
     @Nullable
     public String subtitle() {
         return subtitle;

Core/src/main/java/com/plotsquared/core/plot/flag/FlagContainer.java

@@ -358,6 +358,7 @@ public class FlagContainer {
      * This is to prevent memory leaks. This method is not part of the API.
      *
      * @return a new Runnable that cleans up once the FlagContainer isn't needed anymore.
+     * @since 6.0.10
      */
     @AnnotationHelper.ApiDescription(info = "This method should not be considered as public or API.")
     public Runnable createCleanupHook() {

Core/src/main/java/com/plotsquared/core/plot/flag/PlotFlag.java

@@ -163,6 +163,7 @@ public abstract class PlotFlag<T, F extends PlotFlag<T, F>> {
      * Get if the flag's permission should check for values. E.g. plots.flag.set.music.VALUE
      *
      * @return if valued permission
+     * @since 6.0.10
      */
     public boolean isValuedPermission() {
         return true;

Core/src/main/java/com/plotsquared/core/plot/world/SinglePlotArea.java

@@ -83,6 +83,7 @@ public class SinglePlotArea extends GridPlotWorld {
      * Returns true if the given string matches the naming system used to identify single plot worlds
      * e.g. -1_5 represents plot id *;-1;5. "*" being the plot area name given to single plot world
      * {@link com.plotsquared.core.plot.PlotArea}.
+     * @since 6.1.4
      */
     public static boolean isSinglePlotWorld(String worldName) {
         int len = worldName.length();

Core/src/main/java/com/plotsquared/core/queue/ChunkCoordinator.java

@@ -36,6 +36,7 @@ public abstract class ChunkCoordinator implements Runnable {
 
     /**
      * Cancel the chunk coordinator.
+     * @since 6.0.10
      */
     public abstract void cancel();
 

Core/src/main/java/com/plotsquared/core/queue/QueueCoordinator.java

@@ -209,7 +209,7 @@ public abstract class QueueCoordinator {
      *         <br>
      *         Scheduled for removal once we drop the support for versions not supporting 3D biomes.
      */
-    @Deprecated(forRemoval = true)
+    @Deprecated(forRemoval = true, since = "6.0.0")
     public abstract boolean setBiome(int x, int z, @NonNull BiomeType biome);
 
     /**
@@ -327,6 +327,7 @@ public abstract class QueueCoordinator {
      * Enqueue the queue to start it
      *
      * @return success or not
+     * @since 6.0.10
      */
     public boolean enqueue() {
         boolean success = false;

Core/src/main/java/com/plotsquared/core/util/MainUtil.java

@@ -30,7 +30,7 @@ package com.plotsquared.core.util;
  *
  * @deprecated Do not use
  */
-@Deprecated(forRemoval = true)
+@Deprecated(forRemoval = true, since = "6.0.0")
 public class MainUtil {
 
     /**

Core/src/main/java/com/plotsquared/core/util/Permissions.java

@@ -74,6 +74,7 @@ public class Permissions {
      * @param permission Permission
      * @param key        Permission "key"
      * @return {@code true} if the owner has the given permission, else {@code false}
+     * @since 6.0.10
      */
     public static boolean hasKeyedPermission(
             final @NonNull PermissionHolder caller, final @NonNull String permission,

Core/src/main/java/com/plotsquared/core/util/SchematicHandler.java

@@ -127,7 +127,7 @@ public abstract class SchematicHandler {
         this.subscriberFactory = subscriberFactory;
     }
 
-    @Deprecated(forRemoval = true)
+    @Deprecated(forRemoval = true, since = "6.0.0")
     public static void upload(
             @Nullable UUID uuid,
             final @Nullable String file,
@@ -520,7 +520,7 @@ public abstract class SchematicHandler {
         return null;
     }
 
-    @Deprecated(forRemoval = true)
+    @Deprecated(forRemoval = true, since = "6.0.0")
     public void upload(final CompoundTag tag, UUID uuid, String file, RunnableVal<URL> whenDone) {
         if (tag == null) {
             TaskManager.runTask(whenDone);

Core/src/main/java/com/plotsquared/core/util/SetupUtils.java

@@ -35,6 +35,9 @@ public abstract class SetupUtils {
 
     public static HashMap<String, GeneratorWrapper<?>> generators = new HashMap<>();
 
+    /**
+     * @since 6.1.0
+     */
     public abstract void updateGenerators(final boolean force);
 
     public abstract String getGenerator(final PlotArea plotArea);

Core/src/main/java/com/plotsquared/core/util/TabCompletions.java

@@ -84,7 +84,7 @@ public final class TabCompletions {
      * @return List of completions
      * @deprecated In favor {@link #completePlayers(PlotPlayer, String, List)}
      */
-    @Deprecated(forRemoval = true)
+    @Deprecated(forRemoval = true, since = "6.1.3")
     public static @NonNull List<Command> completePlayers(
             final @NonNull String input,
             final @NonNull List<String> existing
@@ -100,6 +100,7 @@ public final class TabCompletions {
      * @param issuer   The player who issued the tab completion
      * @param existing Players that should not be included in completions
      * @return List of completions
+     * @since 6.1.3
      */
     public static @NonNull List<Command> completePlayers(
             final @NonNull PlotPlayer<?> issuer,
@@ -119,7 +120,7 @@ public final class TabCompletions {
      *
      * @deprecated In favor {@link #completeAddedPlayers(PlotPlayer, Plot, String, List)}
      */
-    @Deprecated(forRemoval = true)
+    @Deprecated(forRemoval = true, since = "6.1.3")
     public static @NonNull List<Command> completeAddedPlayers(
             final @NonNull Plot plot,
             final @NonNull String input, final @NonNull List<String> existing
@@ -135,6 +136,7 @@ public final class TabCompletions {
      * @param input    Command input
      * @param existing Players that should not be included in completions
      * @return List of completions
+     * @since 6.1.3
      */
     public static @NonNull List<Command> completeAddedPlayers(
             final @NonNull PlotPlayer<?> issuer,
@@ -266,7 +268,7 @@ public final class TabCompletions {
      * @deprecated In favor {@link #completePlayers(String, PlotPlayer, String, List, Predicate)}
      */
     @SuppressWarnings("unused")
-    @Deprecated(forRemoval = true)
+    @Deprecated(forRemoval = true, since = "6.1.3")
     private static List<Command> completePlayers(
             final @NonNull String cacheIdentifier,
             final @NonNull String input, final @NonNull List<String> existing,
@@ -282,6 +284,7 @@ public final class TabCompletions {
      * @param existing        Players that should not be included in completions
      * @param uuidFilter      Filter applied before caching values
      * @return List of completions
+     * @since 6.1.3
      */
     private static List<Command> completePlayers(
             final @NonNull String cacheIdentifier,

Core/src/main/java/com/plotsquared/core/util/query/PlotQuery.java

@@ -207,6 +207,7 @@ public final class PlotQuery implements Iterable<Plot> {
      *
      * @param owner Owner UUID
      * @return The query instance
+     * @since 6.1.0
      */
     public @NonNull PlotQuery ownersInclude(final @NonNull UUID owner) {
         Preconditions.checkNotNull(owner, "Owner may not be null");
@@ -218,6 +219,7 @@ public final class PlotQuery implements Iterable<Plot> {
      *
      * @param owner Owner
      * @return The query instance
+     * @since 6.1.0
      */
     public @NonNull PlotQuery ownersInclude(final @NonNull PlotPlayer<?> owner) {
         Preconditions.checkNotNull(owner, "Owner may not be null");