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

This commit is contained in:
Alex 2022-01-24 21:46:01 +01:00 committed by GitHub
parent a0594c19ee
commit ff5d79699d
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
29 changed files with 82 additions and 23 deletions

View File

@ -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 {

View File

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

View File

@ -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",

View File

@ -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,

View File

@ -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 {

View File

@ -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,

View File

@ -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);

View File

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

View File

@ -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);

View File

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

View File

@ -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;
}

View File

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

View File

@ -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);

View File

@ -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,

View File

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

View File

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

View File

@ -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;
}

View File

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

View File

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

View File

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

View File

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

View File

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

View File

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

View File

@ -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 {
/**

View File

@ -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,

View File

@ -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);

View File

@ -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);

View File

@ -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,

View File

@ -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");