From a0594c19ee7ee672035d6473bb6ded0cfd886bff Mon Sep 17 00:00:00 2001 From: Alex Date: Mon, 24 Jan 2022 21:43:35 +0100 Subject: [PATCH] docs: Address dangling `@see` tags (#3469) --- .../com/plotsquared/core/PlotSquared.java | 8 +++- .../configuration/caption/LocaleHolder.java | 6 ++- .../plotsquared/core/player/PlotPlayer.java | 7 ++- .../java/com/plotsquared/core/plot/Plot.java | 45 ++++++++++++------- .../core/plot/PlotModificationManager.java | 15 +++++-- .../core/plot/flag/FlagContainer.java | 15 +++++-- .../core/plot/world/PlotAreaManager.java | 5 ++- 7 files changed, 73 insertions(+), 28 deletions(-) diff --git a/Core/src/main/java/com/plotsquared/core/PlotSquared.java b/Core/src/main/java/com/plotsquared/core/PlotSquared.java index c3917d241..f72bab656 100644 --- a/Core/src/main/java/com/plotsquared/core/PlotSquared.java +++ b/Core/src/main/java/com/plotsquared/core/PlotSquared.java @@ -338,9 +338,11 @@ public class PlotSquared { /** * Add a global reference to a plot world. + *

+ * You can remove the reference by calling {@link #removePlotArea(PlotArea)} + *

* * @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. + *

+ * You can register a caption map by calling {@link #registerCaptionMap(String, CaptionMap)} + *

* * @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( diff --git a/Core/src/main/java/com/plotsquared/core/configuration/caption/LocaleHolder.java b/Core/src/main/java/com/plotsquared/core/configuration/caption/LocaleHolder.java index 3bf3dfed1..2d7fcceb8 100644 --- a/Core/src/main/java/com/plotsquared/core/configuration/caption/LocaleHolder.java +++ b/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. + *

+ * You can use {@link ConsolePlayer#getConsole()} for direct access to the {@link ConsolePlayer} + *

* * @return Console locale holder - * @see ConsolePlayer#getConsole() for direct access to the {@link ConsolePlayer} */ @NonNull static LocaleHolder console() { diff --git a/Core/src/main/java/com/plotsquared/core/player/PlotPlayer.java b/Core/src/main/java/com/plotsquared/core/player/PlotPlayer.java index cf6a9504a..ea85afda1 100644 --- a/Core/src/main/java/com/plotsquared/core/player/PlotPlayer.java +++ b/Core/src/main/java/com/plotsquared/core/player/PlotPlayer.java @@ -378,9 +378,12 @@ public abstract class PlotPlayer

implements CommandCaller, OfflinePlotPlayer, /** * Get a {@link Set} of plots owned by this player. * + *

+ * Take a look at {@link PlotSquared} for more searching functions. + * See {@link #getPlotCount()} for the number of plots. + *

+ * * @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 getPlots() { return PlotQuery.newQuery().ownedBy(this).asSet(); diff --git a/Core/src/main/java/com/plotsquared/core/plot/Plot.java b/Core/src/main/java/com/plotsquared/core/plot/Plot.java index 727738912..51c810deb 100644 --- a/Core/src/main/java/com/plotsquared/core/plot/Plot.java +++ b/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) * + *

+ * See {@link Plot#getPlot(Location)} for existing plots + *

+ * * @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) * + *

+ * See {@link Plot#getPlot(Location)} for existing plots + *

+ * * @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) * + *

+ * See {@link Plot#getPlot(Location)} for existing plots + *

+ * * @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) * + *

+ * See {@link Plot#getPlot(Location)} for existing plots + *

+ * * @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. * + *

+ * Use {@link PlotPlayer#getCurrentPlot()} if a player is expected here. + *

+ * * @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()} + * + *

+ * Use {@link #getOwnerAbs()} to get the owner as stored in the database + *

* * @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.
* - The index corresponds to the index of the category in the config * + *

+ * See {@link Settings.Ratings#CATEGORIES} for rating categories + *

+ * * @return Average ratings in each category - * @see Settings.Ratings#CATEGORIES Rating categories */ public @NonNull double[] getAverageRatings() { Map rating; diff --git a/Core/src/main/java/com/plotsquared/core/plot/PlotModificationManager.java b/Core/src/main/java/com/plotsquared/core/plot/PlotModificationManager.java index 982ba650e..31c6e688c 100644 --- a/Core/src/main/java/com/plotsquared/core/plot/PlotModificationManager.java +++ b/Core/src/main/java/com/plotsquared/core/plot/PlotModificationManager.java @@ -190,9 +190,12 @@ public final class PlotModificationManager { /** * Clear the plot * + *

+ * Use {@link #deletePlot(PlotPlayer, Runnable)} to clear and delete a plot + *

+ * * @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 * + *

+ * Use {@link #deletePlot(PlotPlayer, Runnable)} to clear and delete a plot + *

+ * * @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) * + *

+ * Use {@link PlotModificationManager#clear(boolean, boolean, PlotPlayer, Runnable)} to simply clear a plot + *

+ * * @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()) { diff --git a/Core/src/main/java/com/plotsquared/core/plot/flag/FlagContainer.java b/Core/src/main/java/com/plotsquared/core/plot/flag/FlagContainer.java index 1a4f95970..ee19766bb 100644 --- a/Core/src/main/java/com/plotsquared/core/plot/flag/FlagContainer.java +++ b/Core/src/main/java/com/plotsquared/core/plot/flag/FlagContainer.java @@ -142,10 +142,13 @@ public class FlagContainer { /** * Add a flag to the container * + *

+ * Use {@link #addAll(Collection)} to add multiple flags. + *

+ * * @param flag Flag to add * @param flag type * @param flag value type - * @see #addAll(Collection) to add multiple flags */ public > void addFlag(final T flag) { try { @@ -199,8 +202,11 @@ public class FlagContainer { /** * Add all flags to the container * + *

+ * Use {@link #addFlag(PlotFlag)} to add a single flag. + *

+ * * @param flags Flags to add - * @see #addFlag(PlotFlag) to add a single flagg */ public void addAll(final Collection> 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. * + *

+ * Use {@link PlotFlagUpdateType} to see the update types available. + *

+ * * @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); diff --git a/Core/src/main/java/com/plotsquared/core/plot/world/PlotAreaManager.java b/Core/src/main/java/com/plotsquared/core/plot/world/PlotAreaManager.java index edf7563e4..26a2c70b7 100644 --- a/Core/src/main/java/com/plotsquared/core/plot/world/PlotAreaManager.java +++ b/Core/src/main/java/com/plotsquared/core/plot/world/PlotAreaManager.java @@ -196,9 +196,12 @@ public interface PlotAreaManager { /** * Check if a plot world. * + *

+ * Use {@link #getPlotAreaByString(String)} to get the PlotArea object + *

+ * * @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;