docs: Address dangling @see tags (#3469)

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

@@ -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) {
@@ -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/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/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();

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];
@@ -3031,8 +3043,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/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,
@@ -858,11 +864,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/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);

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;