Always call plot events through the event dispatcher

* refactor!: Align plugin's java version with API java version

* fix: Bump Guice to fix private injection on Java 17

Bukkit/build.gradle.kts

@@ -95,11 +95,11 @@ tasks.named<ShadowJar>("shadowJar") {
 tasks {
     withType<Javadoc> {
         val opt = options as StandardJavadocDocletOptions
-        opt.links("https://papermc.io/javadocs/paper/1.17/")
-        opt.links("https://docs.enginehub.org/javadoc/com.sk89q.worldedit/worldedit-core/7.2.7/")
-        opt.links("https://docs.enginehub.org/javadoc/com.sk89q.worldedit/worldedit-bukkit/7.2.7/")
-        opt.links("https://jd.adventure.kyori.net/api/4.9.3/")
-        opt.links("https://google.github.io/guice/api-docs/5.0.1/javadoc/")
+        opt.links("https://papermc.io/javadocs/paper/1.18/")
+        opt.links("https://docs.enginehub.org/javadoc/com.sk89q.worldedit/worldedit-bukkit/" + libs.worldeditBukkit.get().versionConstraint.toString())
+        opt.links("https://javadoc.io/doc/com.plotsquared/PlotSquared-Core/latest/")
+        opt.links("https://jd.adventure.kyori.net/api/" + libs.adventure.get().versionConstraint.toString())
+        opt.links("https://google.github.io/guice/api-docs/" + libs.guice.get().versionConstraint.toString() + "/javadoc/")
         opt.links("https://checkerframework.org/api/")
     }
 }

Bukkit/src/main/java/com/plotsquared/bukkit/listener/BlockEventListener.java

@@ -166,7 +166,7 @@ public class BlockEventListener implements Listener {
         }
         if (Settings.Redstone.DISABLE_OFFLINE) {
             boolean disable = false;
-            if (!plot.getOwner().equals(DBFunc.SERVER)) {
+            if (!DBFunc.SERVER.equals(plot.getOwner())) {
                 if (plot.isMerged()) {
                     disable = true;
                     for (UUID owner : plot.getOwners()) {

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/build.gradle.kts

@@ -54,3 +54,13 @@ tasks.processResources {
         )
     }
 }
+
+tasks {
+    withType<Javadoc> {
+        val opt = options as StandardJavadocDocletOptions
+        opt.links("https://docs.enginehub.org/javadoc/com.sk89q.worldedit/worldedit-core/" + libs.worldeditCore.get().versionConstraint.toString())
+        opt.links("https://jd.adventure.kyori.net/api/" + libs.adventure.get().versionConstraint.toString())
+        opt.links("https://google.github.io/guice/api-docs/" + libs.guice.get().versionConstraint.toString() + "/javadoc/")
+        opt.links("https://checkerframework.org/api/")
+    }
+}

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/PlotSquared.java

@@ -306,7 +306,7 @@ public class PlotSquared {
      *
      * @param version  First version
      * @param version2 Second version
-     * @return true if `version` is >= `version2`
+     * @return {@code true} if `version` is >= `version2`
      */
     public boolean checkVersion(
             final int[] version,
@@ -338,9 +338,11 @@ public class PlotSquared {
 
     /**
      * Add a global reference to a plot world.
+     * <p>
+     * You can remove the reference by calling {@link #removePlotArea(PlotArea)}
+     * </p>
      *
      * @param plotArea the {@link PlotArea} to add.
-     * @see #removePlotArea(PlotArea) To remove the reference
      */
     @SuppressWarnings("unchecked")
     public void addPlotArea(final @NonNull PlotArea plotArea) {
@@ -733,7 +735,7 @@ public class PlotSquared {
      *
      * @param plot      the plot to remove
      * @param callEvent If to call an event about the plot being removed
-     * @return true if plot existed | false if it didn't
+     * @return {@code true} if plot existed | {@code false} if it didn't
      */
     public boolean removePlot(
             final @NonNull Plot plot,
@@ -1476,7 +1478,7 @@ public class PlotSquared {
      *
      * @param world            World name
      * @param chunkCoordinates Chunk coordinates
-     * @return True if the chunk uses non-standard generation, false if not
+     * @return {@code true} if the chunk uses non-standard generation, {@code false} if not
      */
     public boolean isNonStandardGeneration(
             final @NonNull String world,
@@ -1521,10 +1523,12 @@ public class PlotSquared {
     /**
      * Get the caption map belonging to a namespace. If none exists, a dummy
      * caption map will be returned.
+     * <p>
+     * You can register a caption map by calling {@link #registerCaptionMap(String, CaptionMap)}
+     * </p>
      *
      * @param namespace Namespace
      * @return Map instance
-     * @see #registerCaptionMap(String, CaptionMap) To register a caption map
      */
     public @NonNull CaptionMap getCaptionMap(final @NonNull String namespace) {
         return this.captionMaps.computeIfAbsent(

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

@@ -122,7 +122,7 @@ public final class PlotVersion {
      * Compare a given version string with the one cached here.
      *
      * @param versionString the version to compare
-     * @return true if the given version is a "later" version
+     * @return {@code true} if the given version is a "later" version
      */
     public boolean isLaterVersion(final @NonNull String versionString) {
         int dash = versionString.indexOf('-');
@@ -144,7 +144,7 @@ public final class PlotVersion {
      * Compare a given version with the one cached here.
      *
      * @param verArray the version to compare
-     * @return true if the given version is a "later" version
+     * @return {@code true} if the given version is a "later" version
      */
     public boolean isLaterVersion(int[] verArray) {
         if (verArray[0] > version[0]) {

Core/src/main/java/com/plotsquared/core/backup/BackupManager.java

@@ -88,7 +88,7 @@ public interface BackupManager {
      * Returns true if (potentially) destructive actions should cause
      * PlotSquared to create automatic plot backups
      *
-     * @return True if automatic backups are enabled
+     * @return {@code true} if automatic backups are enabled
      */
     boolean shouldAutomaticallyBackup();
 

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/Command.java

@@ -288,7 +288,7 @@ public abstract class Command {
      * @param args     Arguments
      * @param confirm  Instance, Success, Failure
      * @param whenDone task to run when done
-     * @return CompletableFuture true if the command executed fully, false in
+     * @return CompletableFuture {@code true} if the command executed fully, {@code false} in
      *         any other case
      */
     public CompletableFuture<Boolean> execute(

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

@@ -126,7 +126,7 @@ public class Done extends SubCommand {
         long flagValue = System.currentTimeMillis() / 1000;
         PlotFlag<?, ?> plotFlag = plot.getFlagContainer().getFlag(DoneFlag.class)
                 .createFlagInstance(Long.toString(flagValue));
-        PlotFlagAddEvent event = new PlotFlagAddEvent(plotFlag, plot);
+        PlotFlagAddEvent event = eventDispatcher.callFlagAdd(plotFlag, plot);
         if (event.getEventResult() == Result.DENY) {
             player.sendMessage(TranslatableCaption.of("events.event_denied"));
             return;

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

@@ -25,6 +25,7 @@
  */
 package com.plotsquared.core.command;
 
+import com.google.inject.Inject;
 import com.plotsquared.core.PlotSquared;
 import com.plotsquared.core.configuration.Settings;
 import com.plotsquared.core.configuration.caption.CaptionUtility;
@@ -44,6 +45,7 @@ import com.plotsquared.core.plot.flag.InternalFlag;
 import com.plotsquared.core.plot.flag.PlotFlag;
 import com.plotsquared.core.plot.flag.types.IntegerFlag;
 import com.plotsquared.core.plot.flag.types.ListFlag;
+import com.plotsquared.core.util.EventDispatcher;
 import com.plotsquared.core.util.MathMan;
 import com.plotsquared.core.util.Permissions;
 import com.plotsquared.core.util.StringComparison;
@@ -79,8 +81,12 @@ import java.util.stream.Stream;
 @SuppressWarnings("unused")
 public final class FlagCommand extends Command {
 
-    public FlagCommand() {
+    private final EventDispatcher eventDispatcher;
+
+    @Inject
+    public FlagCommand(final @NonNull EventDispatcher eventDispatcher) {
         super(MainCommand.getInstance(), true);
+        this.eventDispatcher = eventDispatcher;
     }
 
     private static boolean sendMessage(PlotPlayer<?> player) {
@@ -114,7 +120,7 @@ public final class FlagCommand extends Command {
                             TranslatableCaption.of("permission.no_permission"),
                             Template.of(
                                     "node",
-                                    perm
+                                    perm + "." + numeric
                             )
                     );
                 }
@@ -165,7 +171,7 @@ public final class FlagCommand extends Command {
     /**
      * Checks if the player is allowed to modify the flags at their current location
      *
-     * @return true if the player is allowed to modify the flags at their current location
+     * @return {@code true} if the player is allowed to modify the flags at their current location
      */
     private static boolean checkRequirements(final @NonNull PlotPlayer<?> player) {
         final Location location = player.getLocation();
@@ -335,7 +341,7 @@ public final class FlagCommand extends Command {
             return;
         }
         Plot plot = player.getLocation().getPlotAbs();
-        PlotFlagAddEvent event = new PlotFlagAddEvent(plotFlag, plot);
+        PlotFlagAddEvent event = eventDispatcher.callFlagAdd(plotFlag, plot);
         if (event.getEventResult() == Result.DENY) {
             player.sendMessage(
                     TranslatableCaption.of("events.event_denied"),
@@ -394,7 +400,7 @@ public final class FlagCommand extends Command {
             return;
         }
         Plot plot = player.getLocation().getPlotAbs();
-        PlotFlagAddEvent event = new PlotFlagAddEvent(plotFlag, plot);
+        PlotFlagAddEvent event = eventDispatcher.callFlagAdd(plotFlag, plot);
         if (event.getEventResult() == Result.DENY) {
             player.sendMessage(
                     TranslatableCaption.of("events.event_denied"),
@@ -463,7 +469,7 @@ public final class FlagCommand extends Command {
             return;
         }
         final Plot plot = player.getLocation().getPlotAbs();
-        PlotFlagRemoveEvent event = new PlotFlagRemoveEvent(flag, plot);
+        PlotFlagRemoveEvent event = eventDispatcher.callFlagRemove(flag, plot);
         if (event.getEventResult() == Result.DENY) {
             player.sendMessage(
                     TranslatableCaption.of("events.event_denied"),
@@ -516,7 +522,7 @@ public final class FlagCommand extends Command {
                     }
                 } else {
                     PlotFlag<?, ?> plotFlag = parsedFlag.createFlagInstance(list);
-                    PlotFlagAddEvent addEvent = new PlotFlagAddEvent(plotFlag, plot);
+                    PlotFlagAddEvent addEvent = eventDispatcher.callFlagAdd(plotFlag, plot);
                     if (addEvent.getEventResult() == Result.DENY) {
                         player.sendMessage(
                                 TranslatableCaption.of("events.event_denied"),

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

@@ -38,10 +38,12 @@ import com.plotsquared.core.plot.PlotInventory;
 import com.plotsquared.core.plot.PlotItemStack;
 import com.plotsquared.core.plot.flag.PlotFlag;
 import com.plotsquared.core.plot.flag.implementations.MusicFlag;
+import com.plotsquared.core.util.EventDispatcher;
 import com.plotsquared.core.util.InventoryUtil;
 import com.plotsquared.core.util.Permissions;
 import com.sk89q.worldedit.world.item.ItemTypes;
 import net.kyori.adventure.text.minimessage.Template;
+import org.checkerframework.checker.nullness.qual.NonNull;
 
 import javax.annotation.Nullable;
 import java.util.Arrays;
@@ -63,10 +65,12 @@ public class Music extends SubCommand {
             );
 
     private final InventoryUtil inventoryUtil;
+    private final EventDispatcher eventDispatcher;
 
     @Inject
-    public Music(final @Nullable InventoryUtil inventoryUtil) {
+    public Music(final @Nullable InventoryUtil inventoryUtil, final @NonNull EventDispatcher eventDispatcher) {
         this.inventoryUtil = inventoryUtil;
+        this.eventDispatcher = eventDispatcher;
     }
 
     @Override
@@ -104,7 +108,7 @@ public class Music extends SubCommand {
                 if (item.getType() == ItemTypes.BEDROCK) {
                     PlotFlag<?, ?> plotFlag = plot.getFlagContainer().getFlag(MusicFlag.class)
                             .createFlagInstance(item.getType());
-                    PlotFlagRemoveEvent event = new PlotFlagRemoveEvent(plotFlag, plot);
+                    PlotFlagRemoveEvent event = eventDispatcher.callFlagRemove(plotFlag, plot);
                     if (event.getEventResult() == Result.DENY) {
                         getPlayer().sendMessage(
                                 TranslatableCaption.of("events.event_denied"),
@@ -121,7 +125,7 @@ public class Music extends SubCommand {
                 } else if (item.getName().toLowerCase(Locale.ENGLISH).contains("disc")) {
                     PlotFlag<?, ?> plotFlag = plot.getFlagContainer().getFlag(MusicFlag.class)
                             .createFlagInstance(item.getType());
-                    PlotFlagAddEvent event = new PlotFlagAddEvent(plotFlag, plot);
+                    PlotFlagAddEvent event = eventDispatcher.callFlagAdd(plotFlag, plot);
                     if (event.getEventResult() == Result.DENY) {
                         getPlayer().sendMessage(
                                 TranslatableCaption.of("events.event_denied"),

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/ConfigurationSection.java

@@ -73,7 +73,7 @@ public interface ConfigurationSection {
      * has been specified, this will return true.
      *
      * @param path Path to check for existence.
-     * @return True if this section contains the requested path, either via
+     * @return {@code true} if this section contains the requested path, either via
      *         default or being set.
      * @throws IllegalArgumentException Thrown when path is {@code null}.
      */
@@ -87,7 +87,7 @@ public interface ConfigurationSection {
      * has been specified, this will still return false.
      *
      * @param path Path to check for existence.
-     * @return True if this section contains the requested path, regardless of
+     * @return {@code true} if this section contains the requested path, regardless of
      *         having a default.
      * @throws IllegalArgumentException Thrown when path is {@code null}.
      */

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/CaptionMap.java

@@ -60,7 +60,7 @@ public interface CaptionMap {
      * Check if the map supports a given locale
      *
      * @param locale Locale
-     * @return True if the map supports the locale
+     * @return {@code true} if the map supports the locale
      */
     boolean supportsLocale(final @NonNull Locale locale);
 

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/ChatFormatter.java

@@ -99,7 +99,7 @@ public interface ChatFormatter {
          * Whether or not the output should escape
          * any formatting keys
          *
-         * @return True if raw output is to be used
+         * @return {@code true} if raw output is to be used
          */
         public boolean isRawOutput() {
             return this.rawOutput;

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/configuration/caption/LocaleHolder.java

@@ -36,10 +36,12 @@ import java.util.Locale;
 public interface LocaleHolder {
 
     /**
-     * Get the console locale holder
+     * Get the console locale holder.
+     * <p>
+     * You can use {@link ConsolePlayer#getConsole()} for direct access to the {@link ConsolePlayer}
+     * </p>
      *
      * @return Console locale holder
-     * @see ConsolePlayer#getConsole() for direct access to the {@link ConsolePlayer}
      */
     @NonNull
     static LocaleHolder console() {

Core/src/main/java/com/plotsquared/core/database/AbstractDB.java

@@ -371,7 +371,7 @@ public interface AbstractDB {
     /**
      * Don't use this method unless you want to ruin someone's server.
      *
-     * @return true if the tables were deleted, false when an error is encountered
+     * @return {@code true} if the tables were deleted, {@code false} when an error is encountered
      */
     boolean deleteTables();
 

Core/src/main/java/com/plotsquared/core/database/Database.java

@@ -52,7 +52,7 @@ public abstract class Database {
     /**
      * Checks if a connection is open with the database.
      *
-     * @return true if the connection is open
+     * @return {@code true} if the connection is open
      * @throws SQLException if the connection cannot be checked
      */
     public abstract boolean checkConnection() throws SQLException;
@@ -67,7 +67,7 @@ public abstract class Database {
     /**
      * Closes the connection with the database.
      *
-     * @return true if successful
+     * @return {@code true} if successful
      * @throws SQLException if the connection cannot be closed
      */
     public abstract boolean closeConnection() throws SQLException;

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/PlayerPlotDeniedEvent.java

@@ -42,7 +42,7 @@ public class PlayerPlotDeniedEvent extends PlotEvent {
      * @param initiator Player that initiated the event
      * @param plot      Plot in which the event occurred
      * @param player    Player that was denied/un-denied
-     * @param added     true of add to deny list, false if removed
+     * @param added     {@code true} of add to deny list, {@code false} if removed
      */
     public PlayerPlotDeniedEvent(PlotPlayer<?> initiator, Plot plot, UUID player, boolean added) {
         super(plot);

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

@@ -45,7 +45,7 @@ public class PlayerPlotHelperEvent extends PlotEvent {
      * @param initiator Player that initiated the event
      * @param plot      Plot in which the event occurred
      * @param player    Player that was added/removed from the helper list
-     * @param added     true of the player was added, false if the player was removed
+     * @param added     {@code true} if the player was added, {@code false} if the player was removed
      */
     public PlayerPlotHelperEvent(PlotPlayer<?> initiator, Plot plot, UUID player, boolean added) {
         super(plot);

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

@@ -42,7 +42,7 @@ public class PlayerPlotTrustedEvent extends PlotEvent {
      * @param initiator Player that initiated the event
      * @param plot      Plot in which the event occurred
      * @param player    Player that was added/removed from the trusted list
-     * @param added     true of the player was added, false if the player was removed
+     * @param added     {@code true} if the player was added, {@code false} if the player was removed
      */
     public PlayerPlotTrustedEvent(PlotPlayer<?> initiator, Plot plot, UUID player, boolean added) {
         super(plot);

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/generator/HybridUtils.java

@@ -45,6 +45,7 @@ import com.plotsquared.core.queue.ChunkQueueCoordinator;
 import com.plotsquared.core.queue.GlobalBlockQueue;
 import com.plotsquared.core.queue.QueueCoordinator;
 import com.plotsquared.core.util.ChunkManager;
+import com.plotsquared.core.util.EventDispatcher;
 import com.plotsquared.core.util.MathMan;
 import com.plotsquared.core.util.RegionManager;
 import com.plotsquared.core.util.RegionUtil;
@@ -93,6 +94,7 @@ public class HybridUtils {
     private final GlobalBlockQueue blockQueue;
     private final WorldUtil worldUtil;
     private final SchematicHandler schematicHandler;
+    private final EventDispatcher eventDispatcher;
 
     @Inject
     public HybridUtils(
@@ -100,13 +102,15 @@ public class HybridUtils {
             final @NonNull ChunkManager chunkManager,
             final @NonNull GlobalBlockQueue blockQueue,
             final @NonNull WorldUtil worldUtil,
-            final @NonNull SchematicHandler schematicHandler
+            final @NonNull SchematicHandler schematicHandler,
+            final @NonNull EventDispatcher eventDispatcher
     ) {
         this.plotAreaManager = plotAreaManager;
         this.chunkManager = chunkManager;
         this.blockQueue = blockQueue;
         this.worldUtil = worldUtil;
         this.schematicHandler = schematicHandler;
+        this.eventDispatcher = eventDispatcher;
     }
 
     public void regeneratePlotWalls(final PlotArea area) {
@@ -348,7 +352,7 @@ public class HybridUtils {
                     result.add(whenDone.value.variety_sd);
                     PlotFlag<?, ?> plotFlag = GlobalFlagContainer.getInstance().getFlag(AnalysisFlag.class).createFlagInstance(
                             result);
-                    PlotFlagAddEvent event = new PlotFlagAddEvent(plotFlag, origin);
+                    PlotFlagAddEvent event = eventDispatcher.callFlagAdd(plotFlag, origin);
                     if (event.getEventResult() == Result.DENY) {
                         return;
                     }

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/player/PlotPlayer.java

@@ -378,9 +378,12 @@ public abstract class PlotPlayer<P> implements CommandCaller, OfflinePlotPlayer,
     /**
      * Get a {@link Set} of plots owned by this player.
      *
+     * <p>
+     * Take a look at {@link PlotSquared} for more searching functions.
+     * See {@link #getPlotCount()} for the number of plots.
+     * </p>
+     *
      * @return a {@link Set} of plots owned by the player
-     * @see PlotSquared for more searching functions
-     * @see #getPlotCount() for the number of plots
      */
     public Set<Plot> getPlots() {
         return PlotQuery.newQuery().ownedBy(this).asSet();
@@ -501,7 +504,7 @@ public abstract class PlotPlayer<P> implements CommandCaller, OfflinePlotPlayer,
      * Retrieves the attribute of this player.
      *
      * @param key metadata key
-     * @return the attribute will be either true or false
+     * @return the attribute will be either {@code true} or {@code false}
      */
     public boolean getAttribute(String key) {
         if (!hasPersistentMeta("attrib_" + key)) {
@@ -572,7 +575,7 @@ public abstract class PlotPlayer<P> implements CommandCaller, OfflinePlotPlayer,
     /**
      * Check if this player is banned.
      *
-     * @return true if the player is banned, false otherwise.
+     * @return {@code true} if the player is banned, {@code false} otherwise.
      */
     public abstract boolean isBanned();
 

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

@@ -219,10 +219,13 @@ public class Plot {
      * Constructor for a new plot.
      * (Only changes after plot.create() will be properly set in the database)
      *
+     * <p>
+     * See {@link Plot#getPlot(Location)} for existing plots
+     * </p>
+     *
      * @param area  the PlotArea where the plot is located
      * @param id    the plot id
      * @param owner the plot owner
-     * @see Plot#getPlot(Location) for existing plots
      */
     public Plot(final PlotArea area, final @NonNull PlotId id, final UUID owner) {
         this(area, id, owner, 0);
@@ -232,9 +235,12 @@ public class Plot {
      * Constructor for an unowned plot.
      * (Only changes after plot.create() will be properly set in the database)
      *
+     * <p>
+     * See {@link Plot#getPlot(Location)} for existing plots
+     * </p>
+     *
      * @param area the PlotArea where the plot is located
      * @param id   the plot id
-     * @see Plot#getPlot(Location) for existing plots
      */
     public Plot(final @NonNull PlotArea area, final @NonNull PlotId id) {
         this(area, id, null, 0);
@@ -245,11 +251,14 @@ public class Plot {
      * The database will ignore any queries regarding temporary plots.
      * Please note that some bulk plot management functions may still affect temporary plots (TODO: fix this)
      *
+     * <p>
+     * See {@link Plot#getPlot(Location)} for existing plots
+     * </p>
+     *
      * @param area  the PlotArea where the plot is located
      * @param id    the plot id
      * @param owner the owner of the plot
      * @param temp  Represents whatever the database manager needs it to
-     * @see Plot#getPlot(Location) for existing plots
      */
     public Plot(final PlotArea area, final @NonNull PlotId id, final UUID owner, final int temp) {
         this.area = area;
@@ -266,6 +275,10 @@ public class Plot {
     /**
      * Constructor for a saved plots (Used by the database manager when plots are fetched)
      *
+     * <p>
+     * See {@link Plot#getPlot(Location)} for existing plots
+     * </p>
+     *
      * @param id        the plot id
      * @param owner     the plot owner
      * @param trusted   the plot trusted players
@@ -278,7 +291,6 @@ public class Plot {
      * @param merged    an array giving merged plots
      * @param timestamp when the plot was created
      * @param temp      value representing whatever DBManager needs to to. Do not touch tbh.
-     * @see Plot#getPlot(Location) for existing plots
      */
     public Plot(
             @NonNull PlotId id,
@@ -418,9 +430,12 @@ public class Plot {
     /**
      * Return a new/cached plot object at a given location.
      *
+     * <p>
+     * Use {@link PlotPlayer#getCurrentPlot()} if a player is expected here.
+     * </p>
+     *
      * @param location the location of the plot
      * @return plot at location or null
-     * @see PlotPlayer#getCurrentPlot() if a player is expected here.
      */
     public static @Nullable Plot getPlot(final @NonNull Location location) {
         final PlotArea pa = location.getPlotArea();
@@ -449,7 +464,7 @@ public class Plot {
      * that could alter the de facto owner of the plot.
      *
      * @return The plot owner of this particular (sub-)plot
-     *         as stored in the database, if one exists. Else, null.
+     * as stored in the database, if one exists. Else, null.
      */
     public @Nullable UUID getOwnerAbs() {
         return this.owner;
@@ -588,10 +603,13 @@ public class Plot {
     /**
      * Get the plot owner of this particular sub-plot.
      * (Merged plots can have multiple owners)
-     * Direct access is discouraged: use getOwners()
+     * Direct access is discouraged: use {@link #getOwners()}
+     *
+     * <p>
+     * Use {@link #getOwnerAbs()} to get the owner as stored in the database
+     * </p>
      *
      * @return Server if ServerPlot flag set, else {@link #getOwnerAbs()}
-     * @see #getOwnerAbs() getOwnerAbs() to get the owner as stored in the database
      */
     public @Nullable UUID getOwner() {
         if (this.getFlag(ServerPlotFlag.class)) {
@@ -1201,12 +1219,6 @@ public class Plot {
      *
      * @return array of entity counts
      * @see RegionManager#countEntities(Plot)
-     *         0 = Entity
-     *         1 = Animal
-     *         2 = Monster
-     *         3 = Mob
-     *         4 = Boat
-     *         5 = Misc
      */
     public int[] countEntities() {
         int[] count = new int[6];
@@ -1225,7 +1237,7 @@ public class Plot {
     /**
      * Returns true if a previous task was running
      *
-     * @return true if a previous task is running
+     * @return {@code true} if a previous task is running
      */
     public int addRunning() {
         int value = this.getRunning();
@@ -1269,7 +1281,7 @@ public class Plot {
     /**
      * Unclaim the plot (does not modify terrain). Changes made to this plot will not be reflected in unclaimed plot objects.
      *
-     * @return false if the Plot has no owner, otherwise true.
+     * @return {@code false} if the Plot has no owner, otherwise {@code true}.
      */
     public boolean unclaim() {
         if (!this.hasOwner()) {
@@ -1686,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;
@@ -1694,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);
     }
@@ -1708,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,
@@ -2669,7 +2682,7 @@ public class Plot {
     /**
      * Checks if the owner of this Plot is online.
      *
-     * @return true if the owner of the Plot is online
+     * @return {@code true} if the owner of the Plot is online
      */
     public boolean isOnline() {
         if (!this.hasOwner()) {
@@ -3031,8 +3044,11 @@ public class Plot {
      * If rating categories are enabled, get the average rating by category.<br>
      * - The index corresponds to the index of the category in the config
      *
+     * <p>
+     * See {@link Settings.Ratings#CATEGORIES} for rating categories
+     * </p>
+     *
      * @return Average ratings in each category
-     * @see Settings.Ratings#CATEGORIES Rating categories
      */
     public @NonNull double[] getAverageRatings() {
         Map<UUID, Integer> rating;

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

@@ -295,7 +295,7 @@ public abstract class PlotArea {
      * Check if a PlotArea is compatible (move/copy etc.).
      *
      * @param plotArea the {@link PlotArea} to compare
-     * @return true if both areas are compatible
+     * @return {@code true} if both areas are compatible
      */
     public boolean isCompatible(final @NonNull PlotArea plotArea) {
         final ConfigurationSection section = this.worldConfiguration.getConfigurationSection("worlds");
@@ -1101,7 +1101,7 @@ public abstract class PlotArea {
      * If a schematic is available, it can be used for plot claiming.
      *
      * @param schematic the schematic to look for.
-     * @return true if the schematic exists, false otherwise.
+     * @return {@code true} if the schematic exists, {@code false} otherwise.
      */
     public boolean hasSchematic(@NonNull String schematic) {
         return getSchematics().contains(schematic.toLowerCase());
@@ -1110,7 +1110,7 @@ public abstract class PlotArea {
     /**
      * Get whether economy is enabled and used on this plot area or not.
      *
-     * @return true if this plot area uses economy, false otherwise.
+     * @return {@code true} if this plot area uses economy, {@code false} otherwise.
      */
     public boolean useEconomy() {
         return useEconomy;
@@ -1119,7 +1119,7 @@ public abstract class PlotArea {
     /**
      * Get whether the plot area is limited by a world border or not.
      *
-     * @return true if the plot area has a world border, false otherwise.
+     * @return {@code true} if the plot area has a world border, {@code false} otherwise.
      */
     public boolean hasWorldBorder() {
         return worldBorder;
@@ -1128,7 +1128,7 @@ public abstract class PlotArea {
     /**
      * Get whether plot signs are allowed or not.
      *
-     * @return true if plot signs are allow, false otherwise.
+     * @return {@code true} if plot signs are allowed, {@code false} otherwise.
      */
     public boolean allowSigns() {
         return allowSigns;
@@ -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

@@ -187,7 +187,7 @@ public abstract class PlotManager {
      * @param plotIds list of PlotIds to finish the merge for
      * @param queue   Nullable {@link QueueCoordinator}. If null, creates own queue and enqueues,
      *                otherwise writes to the queue but does not enqueue.
-     * @return false if part if the merge failed, otherwise true if successful.
+     * @return {@code false} if part if the merge failed, otherwise {@code true} if successful.
      */
     public abstract boolean finishPlotMerge(@NonNull List<PlotId> plotIds, @Nullable QueueCoordinator queue);
 
@@ -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;
     }
@@ -224,7 +224,7 @@ public abstract class PlotManager {
      *
      * @param queue Nullable {@link QueueCoordinator}. If null, creates own queue and enqueues,
      *              otherwise writes to the queue but does not enqueue.
-     * @return true if the wall blocks were successfully set
+     * @return {@code true} if the wall blocks were successfully set
      */
     public boolean regenerateAllPlotWalls(@Nullable QueueCoordinator queue) {
         boolean success = true;

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

@@ -190,9 +190,12 @@ public final class PlotModificationManager {
     /**
      * Clear the plot
      *
+     * <p>
+     * Use {@link #deletePlot(PlotPlayer, Runnable)} to clear and delete a plot
+     * </p>
+     *
      * @param whenDone A runnable to execute when clearing finishes, or null
      * @see #clear(boolean, boolean, PlotPlayer, Runnable)
-     * @see #deletePlot(PlotPlayer, Runnable) to clear and delete a plot
      */
     public void clear(final @Nullable Runnable whenDone) {
         this.clear(false, false, null, whenDone);
@@ -201,11 +204,14 @@ public final class PlotModificationManager {
     /**
      * Clear the plot
      *
+     * <p>
+     * Use {@link #deletePlot(PlotPlayer, Runnable)} to clear and delete a plot
+     * </p>
+     *
      * @param checkRunning Whether or not already executing tasks should be checked
      * @param isDelete     Whether or not the plot is being deleted
      * @param actor        The actor clearing the plot
      * @param whenDone     A runnable to execute when clearing finishes, or null
-     * @see #deletePlot(PlotPlayer, Runnable) to clear and delete a plot
      */
     public boolean clear(
             final boolean checkRunning,
@@ -256,7 +262,9 @@ public final class PlotModificationManager {
                     if (queue.size() > 0) {
                         queue.setCompleteTask(run);
                         queue.enqueue();
+                        return;
                     }
+                    run.run();
                     return;
                 }
                 Plot current = queue.poll();
@@ -448,7 +456,7 @@ public final class PlotModificationManager {
      * - Any setting from before plot creation will not be saved until the server is stopped properly. i.e. Set any values/options after plot
      * creation.
      *
-     * @return true if plot was created successfully
+     * @return {@code true} if plot was created successfully
      */
     public boolean create() {
         return this.create(this.plot.getOwnerAbs(), true);
@@ -792,7 +800,7 @@ public final class PlotModificationManager {
     /**
      * Unlink a plot and remove the roads
      *
-     * @return true if plot was linked
+     * @return {@code true} if plot was linked
      * @see #unlinkPlot(boolean, boolean)
      */
     public boolean unlink() {
@@ -858,11 +866,14 @@ public final class PlotModificationManager {
     /**
      * Delete a plot (use null for the runnable if you don't need to be notified on completion)
      *
+     * <p>
+     * Use {@link PlotModificationManager#clear(boolean, boolean, PlotPlayer, Runnable)} to simply clear a plot
+     * </p>
+     *
      * @param actor    The actor executing the task
      * @param whenDone task to run when plot has been deleted. Nullable
      * @return {@code true} if the deletion was successful, {@code false} if not
      * @see PlotSquared#removePlot(Plot, boolean)
-     * @see PlotModificationManager#clear(boolean, boolean, PlotPlayer, Runnable) to simply clear a plot
      */
     public boolean deletePlot(@Nullable PlotPlayer<?> actor, final Runnable whenDone) {
         if (!this.plot.hasOwner()) {

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/comment/CommentInbox.java

@@ -54,7 +54,7 @@ public abstract class CommentInbox {
     /**
      * @param plot   the plot's inbox to write to
      * @param player the player trying to write the comment
-     * @return true if the player can write a comment on the plot
+     * @return {@code true} if the player can write a comment on the plot
      */
     public boolean canWrite(Plot plot, PlotPlayer<?> player) {
         if (plot == null) {
@@ -68,7 +68,7 @@ public abstract class CommentInbox {
     /**
      * @param plot   the plot's inbox to write to
      * @param player the player trying to modify the inbox
-     * @return true if the player can write a comment on the plot
+     * @return {@code true} if the player can write a comment on the plot
      */
     @SuppressWarnings({"BooleanMethodIsAlwaysInverted"})
     public boolean canModify(Plot plot, PlotPlayer<?> player) {

Core/src/main/java/com/plotsquared/core/plot/expiration/ExpireManager.java

@@ -359,7 +359,7 @@ public class ExpireManager {
                                                 .getFlag(AnalysisFlag.class)
                                                 .createFlagInstance(changed.asList());
                                         PlotFlagAddEvent event =
-                                                new PlotFlagAddEvent(plotFlag, newPlot);
+                                                eventDispatcher.callFlagAdd(plotFlag, plot);
                                         if (event.getEventResult() == Result.DENY) {
                                             return;
                                         }
@@ -451,7 +451,7 @@ public class ExpireManager {
         plot.getPlotModificationManager().deletePlot(null, whenDone);
     }
 
-    @Deprecated(forRemoval = true, since = "TODO")
+    @Deprecated(forRemoval = true, since = "6.4.0")
     public long getAge(UUID uuid) {
         return getAge(uuid, false);
     }
@@ -462,7 +462,7 @@ public class ExpireManager {
      * @param uuid                     the uuid of the owner to check against
      * @param shouldDeleteUnknownOwner {@code true} if an unknown player should be counted as never online
      * @return the millis since the player was last online, or {@link Long#MAX_VALUE} if player was never online
-     * @since TODO
+     * @since 6.4.0
      */
     public long getAge(UUID uuid, final boolean shouldDeleteUnknownOwner) {
         if (PlotSquared.platform().playerManager().getPlayerIfExists(uuid) != null) {

Core/src/main/java/com/plotsquared/core/plot/expiration/ExpiryTask.java

@@ -160,7 +160,7 @@ public class ExpiryTask {
     /**
      * Returns {@code true} if this task respects unknown owners
      * @return {@code true} if unknown owners should be counted as never online
-     * @since TODO
+     * @since 6.4.0
      */
     public boolean shouldDeleteForUnknownOwner() {
         return settings.DELETE_IF_OWNER_IS_UNKNOWN;

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

@@ -142,10 +142,13 @@ public class FlagContainer {
     /**
      * Add a flag to the container
      *
+     * <p>
+     * Use {@link #addAll(Collection)} to add multiple flags.
+     * </p>
+     *
      * @param flag Flag to add
      * @param <T>  flag type
      * @param <V>  flag value type
-     * @see #addAll(Collection) to add multiple flags
      */
     public <V, T extends PlotFlag<V, ?>> void addFlag(final T flag) {
         try {
@@ -199,8 +202,11 @@ public class FlagContainer {
     /**
      * Add all flags to the container
      *
+     * <p>
+     * Use {@link #addFlag(PlotFlag)} to add a single flag.
+     * </p>
+     *
      * @param flags Flags to add
-     * @see #addFlag(PlotFlag) to add a single flagg
      */
     public void addAll(final Collection<PlotFlag<?, ?>> flags) {
         for (final PlotFlag<?, ?> flag : flags) {
@@ -305,8 +311,11 @@ public class FlagContainer {
      * Updates are: a flag being removed, a flag being added or a flag
      * being updated.
      *
+     * <p>
+     * Use {@link PlotFlagUpdateType} to see the update types available.
+     * </p>
+     *
      * @param plotFlagUpdateHandler The update handler which will react to changes.
-     * @see PlotFlagUpdateType Plot flag update types
      */
     public void subscribe(final @NonNull PlotFlagUpdateHandler plotFlagUpdateHandler) {
         this.updateSubscribers.add(plotFlagUpdateHandler);
@@ -349,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/PlotAreaManager.java

@@ -196,9 +196,12 @@ public interface PlotAreaManager {
     /**
      * Check if a plot world.
      *
+     * <p>
+     * Use {@link #getPlotAreaByString(String)} to get the PlotArea object
+     * </p>
+     *
      * @param world the world
      * @return if a plot world is registered
-     * @see #getPlotAreaByString(String) to get the PlotArea object
      */
     default boolean hasPlotArea(final @NonNull String world) {
         return this.getPlotAreas(world, null).length != 0;

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/ChunkUtil.java

@@ -123,7 +123,7 @@ public class ChunkUtil {
      * @param pos1  Region minimum point
      * @param pos2  Region maximum point
      * @param chunk BlockVector2 of chunk coordinates
-     * @return true if the region pos1-pos2 contains the chunk
+     * @return {@code true} if the region pos1-pos2 contains the chunk
      */
     public static boolean isWholeChunk(@NonNull Location pos1, @NonNull Location pos2, @NonNull BlockVector2 chunk) {
         int x1 = pos1.getX();

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/PlayerManager.java

@@ -166,7 +166,7 @@ public abstract class PlayerManager<P extends PlotPlayer<? extends T>, T> {
      * @return The player's name, None, Everyone or Unknown
      * @deprecated Use {@link #resolveName(UUID)}
      */
-    @Deprecated(forRemoval = true, since = "TODO")
+    @Deprecated(forRemoval = true, since = "6.4.0")
     public static @NonNull String getName(final @Nullable UUID owner) {
         return getName(owner, true);
     }
@@ -179,7 +179,7 @@ public abstract class PlayerManager<P extends PlotPlayer<? extends T>, T> {
      * @return The player's name, None, Everyone or Unknown
      * @deprecated Use {@link #resolveName(UUID, boolean)}
      */
-    @Deprecated(forRemoval = true, since = "TODO")
+    @Deprecated(forRemoval = true, since = "6.4.0")
     public static @NonNull String getName(final @Nullable UUID owner, final boolean blocking) {
         if (owner == null) {
             TranslatableCaption.of("info.none");
@@ -217,7 +217,7 @@ public abstract class PlayerManager<P extends PlotPlayer<? extends T>, T> {
      * @param owner The UUID of the owner
      * @return A caption containing either the name, {@code None}, {@code Everyone} or {@code Unknown}
      * @see #resolveName(UUID, boolean)
-     * @since TODO
+     * @since 6.4.0
      */
     public static @NonNull Caption resolveName(final @Nullable UUID owner) {
         return resolveName(owner, true);
@@ -229,7 +229,7 @@ public abstract class PlayerManager<P extends PlotPlayer<? extends T>, T> {
      * @param owner    The UUID of the owner
      * @param blocking If the operation should block the current thread for {@link Settings.UUID#BLOCKING_TIMEOUT} milliseconds
      * @return A caption containing either the name, {@code None}, {@code Everyone} or {@code Unknown}
-     * @since TODO
+     * @since 6.4.0
      */
     public static @NonNull Caption resolveName(final @Nullable UUID owner, final boolean blocking) {
         if (owner == null) {

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

@@ -52,7 +52,7 @@ public class PremiumVerification {
 
     /**
      * @param userID Spigot user ID
-     * @return true if userID does not contain __USER__
+     * @return {@code true} if userID does not contain __USER__
      */
     private static Boolean isPremium(String userID) {
         return !userID.contains("__USER__");
@@ -61,7 +61,7 @@ public class PremiumVerification {
     /**
      * Returns true if this plugin is premium
      *
-     * @return if is premium
+     * @return {@code true} if is premium
      */
     public static Boolean isPremium() {
         return usingPremium == null ? (usingPremium = isPremium(getUserID())) : usingPremium;

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

@@ -120,7 +120,7 @@ public abstract class RegionManager {
      * @param actor   the actor associated with the cuboid set
      * @param queue   Nullable {@link QueueCoordinator}. If null, creates own queue and enqueues,
      *                otherwise writes to the queue but does not enqueue.
-     * @return true if not enqueued, otherwise whether the created queue enqueued.
+     * @return {@code true} if not enqueued, otherwise whether the created queue enqueued.
      */
     public boolean setCuboids(
             final @NonNull PlotArea area,
@@ -161,7 +161,7 @@ public abstract class RegionManager {
      * Notify any plugins that may want to modify clear behaviour that a clear is occuring
      *
      * @param manager plot manager
-     * @return true if the notified will accept the clear task
+     * @return {@code true} if the notified will accept the clear task
      */
     public boolean notifyClear(PlotManager manager) {
         return false;
@@ -174,7 +174,7 @@ public abstract class RegionManager {
      * @param whenDone task to run when complete
      * @param manager  plot manager
      * @param actor    the player running the clear
-     * @return true if the clear worked. False if someone went wrong so P2 can then handle the clear
+     * @return {@code true} if the clear worked. {@code false} if someone went wrong so P2 can then handle the clear
      */
     public abstract boolean handleClear(
             @NonNull Plot plot,

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);
@@ -543,7 +543,7 @@ public abstract class SchematicHandler {
      *
      * @param tag  to save
      * @param path to save in
-     * @return true if succeeded
+     * @return {@code true} if succeeded
      */
     public boolean save(CompoundTag tag, String path) {
         if (tag == null) {

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/StringMan.java

@@ -328,7 +328,7 @@ public class StringMan {
     /**
      * @param message an input string
      * @return a list of strings
-     * @since TODO
+     * @since 6.4.0
      *
      *         <table border="1">
      *         <caption>Converts multiple quoted and single strings into a list of strings</caption>

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");
@@ -419,7 +421,7 @@ public final class PlotQuery implements Iterable<Plot> {
      * Get whether any provided plot matches the given filters.
      * If no plot was provided, false will be returned.
      *
-     * @return true if any provided plot matches the filters.
+     * @return {@code true} if any provided plot matches the filters.
      */
     public boolean anyMatch() {
         if (this.filters.isEmpty()) {

Core/src/main/java/com/plotsquared/core/uuid/UUIDService.java

@@ -70,7 +70,7 @@ public interface UUIDService {
      * Check whether or not this service can be safely used synchronously
      * without blocking the server for an extended amount of time.
      *
-     * @return True if the service can be used synchronously
+     * @return {@code true} if the service can be used synchronously
      */
     default boolean canBeSynchronous() {
         return false;

build.gradle.kts

@@ -18,7 +18,7 @@ plugins {
     idea
 }
 
-version = "6.3.1-SNAPSHOT"
+version = "6.4.1-SNAPSHOT"
 
 allprojects {
     group = "com.plotsquared"
@@ -77,7 +77,7 @@ allprojects {
     }
 
     tasks.compileJava.configure {
-        options.release.set(16)
+        options.release.set(17)
     }
 
     configurations.all {

gradle/libs.versions.toml

@@ -7,7 +7,7 @@ guava = "31.0.1-jre" # Version set by Minecraft
 # Platform expectations
 paper = "1.18.1-R0.1-SNAPSHOT"
 checker-qual = "3.21.1"
-guice = "5.0.1"
+guice = "5.1.0"
 findbugs = "3.0.1"
 snakeyaml = "1.30" # Version set by Bukkit