diff --git a/.checkstyle/suppressions.xml b/.checkstyle/suppressions.xml index 549f4e95f..b59cd7962 100644 --- a/.checkstyle/suppressions.xml +++ b/.checkstyle/suppressions.xml @@ -2,5 +2,6 @@ + diff --git a/Essentials/src/com/earth2me/essentials/IEssentials.java b/Essentials/src/com/earth2me/essentials/IEssentials.java index f17d9c131..6bc9662a8 100644 --- a/Essentials/src/com/earth2me/essentials/IEssentials.java +++ b/Essentials/src/com/earth2me/essentials/IEssentials.java @@ -94,6 +94,12 @@ public interface IEssentials extends Plugin { EssentialsTimer getTimer(); + /** + * Get a list of players who are vanished. + * + * @return A list of players who are vanished + * @deprecated Use {@link net.ess3.api.IEssentials#getVanishedPlayersNew()} where possible. + */ @Deprecated List getVanishedPlayers(); diff --git a/Essentials/src/com/earth2me/essentials/IUser.java b/Essentials/src/com/earth2me/essentials/IUser.java index f442ae580..8d1a48d9c 100644 --- a/Essentials/src/com/earth2me/essentials/IUser.java +++ b/Essentials/src/com/earth2me/essentials/IUser.java @@ -16,6 +16,12 @@ import java.util.Map; import java.util.Set; import java.util.regex.Pattern; +/** + * Provides access to the user abstraction and stored data. Maintainers should add methods to this interface. + * + * @deprecated External plugins should use {@link net.ess3.api.IUser} instead of this interface, in case future APIs are added. + */ +@Deprecated public interface IUser { boolean isAuthorized(String node); diff --git a/Essentials/src/com/earth2me/essentials/Warps.java b/Essentials/src/com/earth2me/essentials/Warps.java index ef7a9a7c3..828c3cfaa 100644 --- a/Essentials/src/com/earth2me/essentials/Warps.java +++ b/Essentials/src/com/earth2me/essentials/Warps.java @@ -136,8 +136,11 @@ public class Warps implements IConf, net.ess3.api.IWarps { } } - //This is here for future 3.x api support. Not implemented here becasue storage is handled differently + /** + * @deprecated This method relates to the abandoned 3.x storage refactor and is not implemented. + */ @Override + @Deprecated public File getWarpFile(final String name) throws InvalidNameException { throw new UnsupportedOperationException("Not supported yet."); } diff --git a/Essentials/src/com/earth2me/essentials/api/Economy.java b/Essentials/src/com/earth2me/essentials/api/Economy.java index 0a7f88b24..29780d5cb 100644 --- a/Essentials/src/com/earth2me/essentials/api/Economy.java +++ b/Essentials/src/com/earth2me/essentials/api/Economy.java @@ -132,6 +132,13 @@ public class Economy { return getMoneyExact(user); } + /** + * Get the exact balance of the account with the given UUID. + * + * @param uuid The UUID of the user account to retrieve the balance for + * @return The account's balance + * @throws UserDoesNotExistException If the user does not exist + */ public static BigDecimal getMoneyExact(final UUID uuid) throws UserDoesNotExistException { final User user = getUserByUUID(uuid); if (user == null) { @@ -140,6 +147,12 @@ public class Economy { return getMoneyExact(user); } + /** + * Get the exact balance of the account with the given UUID. + * + * @param user The user account to retrieve the balance for + * @return The account's balance + */ public static BigDecimal getMoneyExact(final User user) { if (user == null) { throw new IllegalArgumentException("Economy user cannot be null"); @@ -792,6 +805,7 @@ public class Economy { * * @param amount The amount of money * @return Formatted money + * @deprecated Use {@link #format(BigDecimal)} if your input is already a {@link BigDecimal}. */ @Deprecated public static String format(final double amount) { @@ -803,6 +817,12 @@ public class Economy { } } + /** + * Formats the amount of money like all other Essentials functions. Example: $100000 or $12345.67 + * + * @param amount The amount of money + * @return Formatted money + */ public static String format(final BigDecimal amount) { if (ess == null) { throw new RuntimeException(noCallBeforeLoad); diff --git a/Essentials/src/com/earth2me/essentials/api/IAsyncTeleport.java b/Essentials/src/com/earth2me/essentials/api/IAsyncTeleport.java index f92ef47db..6a7169a1d 100644 --- a/Essentials/src/com/earth2me/essentials/api/IAsyncTeleport.java +++ b/Essentials/src/com/earth2me/essentials/api/IAsyncTeleport.java @@ -8,6 +8,10 @@ import org.bukkit.event.player.PlayerTeleportEvent; import java.util.concurrent.CompletableFuture; +/** + * Manages EssentialsX's teleport functionality for a player. + * Use this if you want to access EssentialsX's async/safe teleport functionality and teleport warmups and cooldowns. + */ public interface IAsyncTeleport { /** diff --git a/Essentials/src/com/earth2me/essentials/api/II18n.java b/Essentials/src/com/earth2me/essentials/api/II18n.java index c6da43943..01d0b2b18 100644 --- a/Essentials/src/com/earth2me/essentials/api/II18n.java +++ b/Essentials/src/com/earth2me/essentials/api/II18n.java @@ -1,7 +1,16 @@ package com.earth2me.essentials.api; +import org.bukkit.entity.Player; + import java.util.Locale; +/** + * Provides access to the current locale in use. + * + * @deprecated External plugins should prefer to use either the player's client language ({@link Player#getLocale()} or + * {@link net.ess3.api.II18n} in case of future additions. + */ +@Deprecated public interface II18n { /** * Gets the current locale setting diff --git a/Essentials/src/com/earth2me/essentials/api/IItemDb.java b/Essentials/src/com/earth2me/essentials/api/IItemDb.java index d9143f2d5..7f104fdd5 100644 --- a/Essentials/src/com/earth2me/essentials/api/IItemDb.java +++ b/Essentials/src/com/earth2me/essentials/api/IItemDb.java @@ -11,6 +11,13 @@ import java.util.Collection; import java.util.List; import java.util.Locale; +/** + * Provides access to the current item alias registry. + * + * @deprecated External plugins should use {@link net.ess3.api.IItemDb} instead, which includes access to {@link net.ess3.api.IItemDb.ItemResolver} + * APIs. + */ +@Deprecated public interface IItemDb { /** diff --git a/Essentials/src/com/earth2me/essentials/api/IJails.java b/Essentials/src/com/earth2me/essentials/api/IJails.java index a1e1ee4a9..9a779e980 100644 --- a/Essentials/src/com/earth2me/essentials/api/IJails.java +++ b/Essentials/src/com/earth2me/essentials/api/IJails.java @@ -6,6 +6,12 @@ import org.bukkit.Location; import java.util.Collection; import java.util.concurrent.CompletableFuture; +/** + * Provides access to the storage of jail locations. Maintainers should add methods to this interface. + * + * @deprecated External plugins should use {@link net.ess3.api.IJails} instead of this interface in case future APIs are added. + */ +@Deprecated public interface IJails extends IReload { /** * Gets the location of the jail with the given name diff --git a/Essentials/src/com/earth2me/essentials/api/IReload.java b/Essentials/src/com/earth2me/essentials/api/IReload.java index c2a9ed13f..1cacf8f79 100644 --- a/Essentials/src/com/earth2me/essentials/api/IReload.java +++ b/Essentials/src/com/earth2me/essentials/api/IReload.java @@ -1,5 +1,15 @@ package com.earth2me.essentials.api; +/** + * Represents a storage object that is reloadable. + * + * @deprecated This is a remnant of the abandoned 3.x storage system. Neither future 2.x code nor external plugins + * should use this interface. + */ +@Deprecated public interface IReload { + /** + * Reloads the given storage object. + */ void onReload(); } diff --git a/Essentials/src/com/earth2me/essentials/api/ITeleport.java b/Essentials/src/com/earth2me/essentials/api/ITeleport.java index a80b75717..4bc66bffe 100644 --- a/Essentials/src/com/earth2me/essentials/api/ITeleport.java +++ b/Essentials/src/com/earth2me/essentials/api/ITeleport.java @@ -7,7 +7,7 @@ import org.bukkit.entity.Player; import org.bukkit.event.player.PlayerTeleportEvent; /** - * @deprecated This API is not asynchronous. Use {@link com.earth2me.essentials.api.IAsyncTeleport IAsyncTeleport} + * @deprecated This API is not asynchronous and is no longer maintained. Use {@link com.earth2me.essentials.api.IAsyncTeleport IAsyncTeleport}. */ public interface ITeleport { /** @@ -32,6 +32,13 @@ public interface ITeleport { @Deprecated void now(Player entity, boolean cooldown, PlayerTeleportEvent.TeleportCause cause) throws Exception; + /** + * Teleport a player to a specific location + * + * @param loc - Where should the player end up + * @param chargeFor - What the user will be charged if teleportPlayer is successful + * @throws Exception + */ @Deprecated void teleport(Location loc, Trade chargeFor) throws Exception; diff --git a/Essentials/src/com/earth2me/essentials/api/IWarps.java b/Essentials/src/com/earth2me/essentials/api/IWarps.java index c5f46229e..89f0fb47e 100644 --- a/Essentials/src/com/earth2me/essentials/api/IWarps.java +++ b/Essentials/src/com/earth2me/essentials/api/IWarps.java @@ -9,6 +9,12 @@ import java.io.File; import java.util.Collection; import java.util.UUID; +/** + * Provides access to the storage of warp locations. Maintainers should add methods to this interface. + * + * @deprecated External plugins should use {@link net.ess3.api.IWarps} instead of this interface, in case future APIs are added. + */ +@Deprecated public interface IWarps extends IConf { /** * Get a warp by name @@ -16,7 +22,7 @@ public interface IWarps extends IConf { * @param warp - Warp name * @return - Location the warp is set to * @throws WarpNotFoundException When the warp is not found - * @throws InvalidWorldException When the world the warp is in is not found + * @throws net.ess3.api.InvalidWorldException When the world the warp is in is not found */ Location getWarp(String warp) throws WarpNotFoundException, net.ess3.api.InvalidWorldException; @@ -77,11 +83,8 @@ public interface IWarps extends IConf { boolean isEmpty(); /** - * Get a warp file note: this is not yet implemented, as 3.x uses different storage methods - * - * @param name - name of file - * @return - an instance of the file - * @throws InvalidNameException - When the file is not found + * @deprecated This method relates to the abandoned 3.x storage refactor and is not implemented. */ + @Deprecated File getWarpFile(String name) throws net.ess3.api.InvalidNameException; } diff --git a/Essentials/src/com/earth2me/essentials/api/InvalidNameException.java b/Essentials/src/com/earth2me/essentials/api/InvalidNameException.java index 0036ced55..073587147 100644 --- a/Essentials/src/com/earth2me/essentials/api/InvalidNameException.java +++ b/Essentials/src/com/earth2me/essentials/api/InvalidNameException.java @@ -1,5 +1,9 @@ package com.earth2me.essentials.api; +/** + * @deprecated This exception relates to the abandoned 3.x storage refactor and is not implemented. + */ +@Deprecated public class InvalidNameException extends Exception { /** * NOTE: This is not implemented yet, just here for future 3.x api support Allow serialization of the diff --git a/Essentials/src/com/earth2me/essentials/api/InvalidWorldException.java b/Essentials/src/com/earth2me/essentials/api/InvalidWorldException.java index a2b3fbe7d..c6b0931d8 100644 --- a/Essentials/src/com/earth2me/essentials/api/InvalidWorldException.java +++ b/Essentials/src/com/earth2me/essentials/api/InvalidWorldException.java @@ -2,6 +2,10 @@ package com.earth2me.essentials.api; import static com.earth2me.essentials.I18n.tl; +/** + * @deprecated This exception is unused. Use {@link net.ess3.api.InvalidWorldException} instead. + */ +@Deprecated public class InvalidWorldException extends Exception { private final String world; diff --git a/Essentials/src/com/earth2me/essentials/api/NoLoanPermittedException.java b/Essentials/src/com/earth2me/essentials/api/NoLoanPermittedException.java index b0527a1c3..b26d3ccb7 100644 --- a/Essentials/src/com/earth2me/essentials/api/NoLoanPermittedException.java +++ b/Essentials/src/com/earth2me/essentials/api/NoLoanPermittedException.java @@ -1,5 +1,8 @@ package com.earth2me.essentials.api; +/** + * Thrown when a user does not have the balance for a transaction and cannot take a loan. + */ public class NoLoanPermittedException extends net.ess3.api.NoLoanPermittedException { } diff --git a/Essentials/src/com/earth2me/essentials/api/UserDoesNotExistException.java b/Essentials/src/com/earth2me/essentials/api/UserDoesNotExistException.java index c2889dd7b..27504edd1 100644 --- a/Essentials/src/com/earth2me/essentials/api/UserDoesNotExistException.java +++ b/Essentials/src/com/earth2me/essentials/api/UserDoesNotExistException.java @@ -4,6 +4,9 @@ import java.util.UUID; import static com.earth2me.essentials.I18n.tl; +/** + * Thrown when the requested user does not exist. + */ public class UserDoesNotExistException extends Exception { public UserDoesNotExistException(final String name) { super(tl("userDoesNotExist", name)); diff --git a/Essentials/src/net/ess3/api/Economy.java b/Essentials/src/net/ess3/api/Economy.java index c18a3c360..7e2aab7b9 100644 --- a/Essentials/src/net/ess3/api/Economy.java +++ b/Essentials/src/net/ess3/api/Economy.java @@ -1,5 +1,12 @@ package net.ess3.api; +/** + * Do not use this class. + * This class proxies {@link com.earth2me.essentials.api.Economy}. + *

+ * If you want to interact with EssentialsX's economy, we recommend using Vault or {@link com.earth2me.essentials.api.Economy}. + */ +@Deprecated public class Economy extends com.earth2me.essentials.api.Economy { } diff --git a/Essentials/src/net/ess3/api/IEssentials.java b/Essentials/src/net/ess3/api/IEssentials.java index 0c13aee98..a9039d3b9 100644 --- a/Essentials/src/net/ess3/api/IEssentials.java +++ b/Essentials/src/net/ess3/api/IEssentials.java @@ -6,13 +6,40 @@ import net.ess3.provider.SpawnEggProvider; import java.util.Collection; +/** + * This interface exposes certain extra methods implemented in the main class that are not implemented in {@link com.earth2me.essentials.IEssentials}. + * External plugins should use this class instead of {@link com.earth2me.essentials.Essentials} or {@link com.earth2me.essentials.IEssentials} where possible. + */ public interface IEssentials extends com.earth2me.essentials.IEssentials { + /** + * Get a list of players who are vanished. + * + * @return A list of players who are vanished + */ Collection getVanishedPlayersNew(); + /** + * Get the spawn egg provider for the current platform. + * + * @return The current active spawn egg provider + */ SpawnEggProvider getSpawnEggProvider(); + /** + * Get the potion meta provider for the current platform. + * + * @return The current active potion meta provider + */ PotionMetaProvider getPotionMetaProvider(); + /** + * Get the {@link CustomItemResolver} that is currently in use. + * + * Note: external plugins should generally avoid using this. If you want to add custom items from your plugin, + * you probably want to implement your own {@link net.ess3.api.IItemDb.ItemResolver}. + * + * @return + */ CustomItemResolver getCustomItemResolver(); } diff --git a/Essentials/src/net/ess3/api/II18n.java b/Essentials/src/net/ess3/api/II18n.java index 423b884fc..dd6f4cef2 100644 --- a/Essentials/src/net/ess3/api/II18n.java +++ b/Essentials/src/net/ess3/api/II18n.java @@ -1,5 +1,8 @@ package net.ess3.api; +/** + * Provides access to the current locale in use. + */ public interface II18n extends com.earth2me.essentials.api.II18n { } diff --git a/Essentials/src/net/ess3/api/IItemDb.java b/Essentials/src/net/ess3/api/IItemDb.java index da4f6e1bc..eda06273d 100644 --- a/Essentials/src/net/ess3/api/IItemDb.java +++ b/Essentials/src/net/ess3/api/IItemDb.java @@ -7,6 +7,9 @@ import java.util.Collection; import java.util.Map; import java.util.function.Function; +/** + * Provides access to the current item alias registry, and allows registration of custom item resolvers. + */ public interface IItemDb extends com.earth2me.essentials.api.IItemDb { /** @@ -65,6 +68,10 @@ public interface IItemDb extends com.earth2me.essentials.api.IItemDb { /** * Create a stack from the given name with the maximum stack size for that material. * + * Note: it is unlikely that external plugins will need to call this method directly. In most cases, {@link IItemDb#get(String)} + * and {@link IItemDb#get(String, int)} should be sufficient. However, if you intend to perform an item lookup inside + * a {@link ItemResolver} implementation, you must call this method with useResolvers as false to prevent recursion. + * * @param name Item name to look up in the database * @param useResolvers Whether to call other plugins' resolver functions before looking the * item up in the database @@ -81,9 +88,15 @@ public interface IItemDb extends com.earth2me.essentials.api.IItemDb { * @param useResolvers Whether to call other plugins' item resolvers before looking the * item up in the database * @return A string representation of the given item stack + * @deprecated This will soon be replaced with a new two-way API. It should not be relied upon by external plugins! */ + @Deprecated String serialize(ItemStack itemStack, boolean useResolvers); + /** + * A service capable of resolving custom item names to items and vice versa, as well as adding extra item names to + * tab complete suggestions. + */ @FunctionalInterface interface ItemResolver extends Function { diff --git a/Essentials/src/net/ess3/api/IJails.java b/Essentials/src/net/ess3/api/IJails.java index 18c7342d9..8f93aa6a2 100644 --- a/Essentials/src/net/ess3/api/IJails.java +++ b/Essentials/src/net/ess3/api/IJails.java @@ -1,5 +1,10 @@ package net.ess3.api; +/** + * This interface may contain future additions to the jails API on top of {@link com.earth2me.essentials.api.IJails}. + * + * Note: Maintainers should add methods to {@link com.earth2me.essentials.api.IWarps}. + */ public interface IJails extends com.earth2me.essentials.api.IJails { } diff --git a/Essentials/src/net/ess3/api/IReload.java b/Essentials/src/net/ess3/api/IReload.java index 1d6ae518e..734708930 100644 --- a/Essentials/src/net/ess3/api/IReload.java +++ b/Essentials/src/net/ess3/api/IReload.java @@ -1,5 +1,12 @@ package net.ess3.api; +/** + * Represents a storage object that is reloadable. + * + * @deprecated This is a remnant of the abandoned 3.x storage system. Neither future 2.x code nor external plugins + * should use this interface. + */ +@Deprecated public interface IReload extends com.earth2me.essentials.api.IReload { } diff --git a/Essentials/src/net/ess3/api/ISettings.java b/Essentials/src/net/ess3/api/ISettings.java index d1a9b9743..b473ef946 100644 --- a/Essentials/src/net/ess3/api/ISettings.java +++ b/Essentials/src/net/ess3/api/ISettings.java @@ -1,4 +1,7 @@ package net.ess3.api; +/** + * + */ public interface ISettings extends com.earth2me.essentials.ISettings { } diff --git a/Essentials/src/net/ess3/api/IUser.java b/Essentials/src/net/ess3/api/IUser.java index 1816a2ef3..7911b7103 100644 --- a/Essentials/src/net/ess3/api/IUser.java +++ b/Essentials/src/net/ess3/api/IUser.java @@ -1,5 +1,10 @@ package net.ess3.api; +/** + * This interface may contain future additions to the warps API on top of {@link com.earth2me.essentials.IUser}. + * + * Note: Maintainers should add methods to {@link com.earth2me.essentials.IUser}. + */ public interface IUser extends com.earth2me.essentials.IUser { } diff --git a/Essentials/src/net/ess3/api/IWarps.java b/Essentials/src/net/ess3/api/IWarps.java index f3a5d8656..9daef85d5 100644 --- a/Essentials/src/net/ess3/api/IWarps.java +++ b/Essentials/src/net/ess3/api/IWarps.java @@ -1,5 +1,10 @@ package net.ess3.api; +/** + * This interface may contain future additions to the warps API on top of {@link com.earth2me.essentials.api.IWarps}. + * + * Note: Maintainers should add methods to {@link com.earth2me.essentials.api.IWarps}. + */ public interface IWarps extends com.earth2me.essentials.api.IWarps { } diff --git a/Essentials/src/net/ess3/api/InvalidNameException.java b/Essentials/src/net/ess3/api/InvalidNameException.java index 0b108b7ae..ac77e6d4f 100644 --- a/Essentials/src/net/ess3/api/InvalidNameException.java +++ b/Essentials/src/net/ess3/api/InvalidNameException.java @@ -1,9 +1,14 @@ package net.ess3.api; +/** + * @deprecated This exception relates to the abandoned 3.x storage refactor and is not implemented. + */ +@Deprecated public class InvalidNameException extends Exception { /** - * NOTE: This is not implemented yet, just here for future 3.x api support Allow serialization of the - * InvalidNameException exception + * Allow serialization of the InvalidNameException exception + * + * NOTE: This is not implemented yet, just here for future 3.x api support */ private static final long serialVersionUID = 1485321420293663139L; diff --git a/Essentials/src/net/ess3/api/InvalidWorldException.java b/Essentials/src/net/ess3/api/InvalidWorldException.java index c641184c8..8f5e89002 100644 --- a/Essentials/src/net/ess3/api/InvalidWorldException.java +++ b/Essentials/src/net/ess3/api/InvalidWorldException.java @@ -2,6 +2,10 @@ package net.ess3.api; import static com.earth2me.essentials.I18n.tl; +/** + * Fired when trying to teleport a user to an invalid world. This usually only occurs if a world has been removed from + * the server and a player tries to teleport to a warp or home in that world. + */ public class InvalidWorldException extends Exception { private final String world; diff --git a/Essentials/src/net/ess3/api/MaxMoneyException.java b/Essentials/src/net/ess3/api/MaxMoneyException.java index b7679c270..54bd573fb 100644 --- a/Essentials/src/net/ess3/api/MaxMoneyException.java +++ b/Essentials/src/net/ess3/api/MaxMoneyException.java @@ -2,6 +2,9 @@ package net.ess3.api; import static com.earth2me.essentials.I18n.tl; +/** + * Thrown when a transaction would put the player's balance above the maximum balance allowed. + */ public class MaxMoneyException extends Exception { public MaxMoneyException() { super(tl("maxMoney")); diff --git a/Essentials/src/net/ess3/api/NoLoanPermittedException.java b/Essentials/src/net/ess3/api/NoLoanPermittedException.java index fa058e258..9633a8204 100644 --- a/Essentials/src/net/ess3/api/NoLoanPermittedException.java +++ b/Essentials/src/net/ess3/api/NoLoanPermittedException.java @@ -2,6 +2,10 @@ package net.ess3.api; import static com.earth2me.essentials.I18n.tl; +/** + * @deprecated You should use {@link com.earth2me.essentials.api.NoLoanPermittedException} instead of this class. + */ +@Deprecated public class NoLoanPermittedException extends Exception { public NoLoanPermittedException() { super(tl("negativeBalanceError")); diff --git a/Essentials/src/net/ess3/api/PluginKey.java b/Essentials/src/net/ess3/api/PluginKey.java index 90ee02490..b133ac474 100644 --- a/Essentials/src/net/ess3/api/PluginKey.java +++ b/Essentials/src/net/ess3/api/PluginKey.java @@ -5,6 +5,9 @@ import org.bukkit.plugin.Plugin; import java.util.Objects; import java.util.UUID; +/** + * A namespaced key that uses plugins as namespaces. + */ public final class PluginKey { private final Plugin plugin; private final String key; @@ -14,10 +17,25 @@ public final class PluginKey { this.key = key; } + /** + * Create a randomly-generated plugin key under the given plugin's namespace. + *

+ * Note: Plugins should prefer to create keys with predictable names - see {@link PluginKey#fromKey(Plugin, String)}. + * + * @param plugin The plugin whose namespace to use + * @return A random key under the given plugin's namespace + */ public static PluginKey random(final Plugin plugin) { return new PluginKey(plugin, UUID.randomUUID().toString()); } + /** + * Create a plugin key under the given plugin's namespace with the given name. + * + * @param plugin The plugin whose namespace to use + * @param key The name of the key to create + * @return The key under the given plugin's namespace. + */ public static PluginKey fromKey(final Plugin plugin, final String key) { return new PluginKey(plugin, key); } diff --git a/Essentials/src/net/ess3/api/UserDoesNotExistException.java b/Essentials/src/net/ess3/api/UserDoesNotExistException.java index 7b5f109fe..dec90e8e2 100644 --- a/Essentials/src/net/ess3/api/UserDoesNotExistException.java +++ b/Essentials/src/net/ess3/api/UserDoesNotExistException.java @@ -2,6 +2,10 @@ package net.ess3.api; import static com.earth2me.essentials.I18n.tl; +/** + * @deprecated This is unused - see {@link com.earth2me.essentials.api.UserDoesNotExistException}. + */ +@Deprecated public class UserDoesNotExistException extends Exception { public UserDoesNotExistException(final String name) { super(tl("userDoesNotExist", name)); diff --git a/Essentials/src/net/ess3/api/events/AfkStatusChangeEvent.java b/Essentials/src/net/ess3/api/events/AfkStatusChangeEvent.java index 5e51fa696..fae2e9be5 100644 --- a/Essentials/src/net/ess3/api/events/AfkStatusChangeEvent.java +++ b/Essentials/src/net/ess3/api/events/AfkStatusChangeEvent.java @@ -2,6 +2,9 @@ package net.ess3.api.events; import net.ess3.api.IUser; +/** + * Fired when a player's AFK status changes. + */ public class AfkStatusChangeEvent extends StatusChangeEvent { private final Cause cause; @@ -19,6 +22,9 @@ public class AfkStatusChangeEvent extends StatusChangeEvent { return cause; } + /** + * The cause of the AFK status change. + */ public enum Cause { ACTIVITY, MOVE, diff --git a/Essentials/src/net/ess3/api/events/FlyStatusChangeEvent.java b/Essentials/src/net/ess3/api/events/FlyStatusChangeEvent.java index 566481b9f..2bd0cf2f0 100644 --- a/Essentials/src/net/ess3/api/events/FlyStatusChangeEvent.java +++ b/Essentials/src/net/ess3/api/events/FlyStatusChangeEvent.java @@ -2,6 +2,9 @@ package net.ess3.api.events; import net.ess3.api.IUser; +/** + * Fired when a player's flight status is toggled using /fly. + */ public class FlyStatusChangeEvent extends StatusChangeEvent { public FlyStatusChangeEvent(final IUser affected, final IUser controller, final boolean value) { super(affected, controller, value); diff --git a/Essentials/src/net/ess3/api/events/JailStatusChangeEvent.java b/Essentials/src/net/ess3/api/events/JailStatusChangeEvent.java index fface4b72..37d1040cb 100644 --- a/Essentials/src/net/ess3/api/events/JailStatusChangeEvent.java +++ b/Essentials/src/net/ess3/api/events/JailStatusChangeEvent.java @@ -2,6 +2,12 @@ package net.ess3.api.events; import net.ess3.api.IUser; +/** + * Fired when a player's jail status changes. + *

+ * Note: when a user is about to be jailed, you currently can't access which jail the user is being put into until after the /togglejail command finishes executing. + * You can, however, access the player's current jail when they are about to be unjailed by calling {@link IUser#getJail()}. + */ public class JailStatusChangeEvent extends StatusChangeEvent { public JailStatusChangeEvent(final IUser affected, final IUser controller, final boolean value) { super(affected, controller, value); diff --git a/Essentials/src/net/ess3/api/events/LocalChatSpyEvent.java b/Essentials/src/net/ess3/api/events/LocalChatSpyEvent.java index 3a1409f40..9829a1291 100644 --- a/Essentials/src/net/ess3/api/events/LocalChatSpyEvent.java +++ b/Essentials/src/net/ess3/api/events/LocalChatSpyEvent.java @@ -10,6 +10,9 @@ import java.util.Set; import static com.earth2me.essentials.I18n.tl; +/** + * Fired when a player uses local chat. + */ public class LocalChatSpyEvent extends Event implements Cancellable { private static final HandlerList handlers = new HandlerList(); private final Player player; diff --git a/Essentials/src/net/ess3/api/events/MuteStatusChangeEvent.java b/Essentials/src/net/ess3/api/events/MuteStatusChangeEvent.java index db2987811..30de86b0e 100644 --- a/Essentials/src/net/ess3/api/events/MuteStatusChangeEvent.java +++ b/Essentials/src/net/ess3/api/events/MuteStatusChangeEvent.java @@ -4,6 +4,9 @@ import net.ess3.api.IUser; import java.util.Optional; +/** + * Fired when a player's mute status is changed. + */ public class MuteStatusChangeEvent extends StatusChangeEvent { private final Long timestamp; private final String reason; diff --git a/Essentials/src/net/ess3/api/events/NickChangeEvent.java b/Essentials/src/net/ess3/api/events/NickChangeEvent.java index 9a1ab9c39..0b9db24f8 100644 --- a/Essentials/src/net/ess3/api/events/NickChangeEvent.java +++ b/Essentials/src/net/ess3/api/events/NickChangeEvent.java @@ -3,6 +3,11 @@ package net.ess3.api.events; import net.ess3.api.IUser; import org.bukkit.event.Cancellable; +/** + * Fired when a player's nickname is changed. + * + * WARNING: The values of {@link NickChangeEvent#getAffected()} and {@link NickChangeEvent#getController()} are inverted due to a long-standing implementation bug. + */ public class NickChangeEvent extends StateChangeEvent implements Cancellable { private final String newValue; @@ -17,7 +22,7 @@ public class NickChangeEvent extends StateChangeEvent implements Cancellable { /** * Get the user who CAUSED the state change. - * (This method is implemented incorrectly.) + * WARNING: This method is inverted - this returns the user who caused the change. * * @return The user who caused the state change. */ @@ -28,7 +33,7 @@ public class NickChangeEvent extends StateChangeEvent implements Cancellable { /** * Get the user who is AFFECTED by the state change. - * (This method is implemented incorrectly.) + * WARNING: This method is inverted - this returns the user who was affected by the change. * * @return The user who is affected by the state change. */ diff --git a/Essentials/src/net/ess3/api/events/SignBreakEvent.java b/Essentials/src/net/ess3/api/events/SignBreakEvent.java index cdb617ebd..a0aff73ac 100644 --- a/Essentials/src/net/ess3/api/events/SignBreakEvent.java +++ b/Essentials/src/net/ess3/api/events/SignBreakEvent.java @@ -3,6 +3,11 @@ package net.ess3.api.events; import com.earth2me.essentials.signs.EssentialsSign; import net.ess3.api.IUser; +/** + * Fired when an Essentials sign is broken. + * + * This is primarily intended for use with EssentialsX's sign abstraction - external plugins should not listen on this event. + */ public class SignBreakEvent extends SignEvent { public SignBreakEvent(final EssentialsSign.ISign sign, final EssentialsSign essSign, final IUser user) { super(sign, essSign, user); diff --git a/Essentials/src/net/ess3/api/events/SignCreateEvent.java b/Essentials/src/net/ess3/api/events/SignCreateEvent.java index 08950e061..bab9227ce 100644 --- a/Essentials/src/net/ess3/api/events/SignCreateEvent.java +++ b/Essentials/src/net/ess3/api/events/SignCreateEvent.java @@ -3,6 +3,11 @@ package net.ess3.api.events; import com.earth2me.essentials.signs.EssentialsSign; import net.ess3.api.IUser; +/** + * Fired when an Essentials sign is created. + * + * This is primarily intended for use with EssentialsX's sign abstraction - external plugins should not listen on this event. + */ public class SignCreateEvent extends SignEvent { public SignCreateEvent(final EssentialsSign.ISign sign, final EssentialsSign essSign, final IUser user) { super(sign, essSign, user); diff --git a/Essentials/src/net/ess3/api/events/SignInteractEvent.java b/Essentials/src/net/ess3/api/events/SignInteractEvent.java index da8055d7f..357880765 100644 --- a/Essentials/src/net/ess3/api/events/SignInteractEvent.java +++ b/Essentials/src/net/ess3/api/events/SignInteractEvent.java @@ -3,6 +3,11 @@ package net.ess3.api.events; import com.earth2me.essentials.signs.EssentialsSign; import net.ess3.api.IUser; +/** + * Fired when an Essentials sign is interacted with. + * + * This is primarily intended for use with EssentialsX's sign abstraction - external plugins should not listen on this event. + */ public class SignInteractEvent extends SignEvent { public SignInteractEvent(final EssentialsSign.ISign sign, final EssentialsSign essSign, final IUser user) { super(sign, essSign, user); diff --git a/Essentials/src/net/ess3/api/events/TPARequestEvent.java b/Essentials/src/net/ess3/api/events/TPARequestEvent.java index 5720e3814..a4ffb38d5 100644 --- a/Essentials/src/net/ess3/api/events/TPARequestEvent.java +++ b/Essentials/src/net/ess3/api/events/TPARequestEvent.java @@ -6,6 +6,9 @@ import org.bukkit.event.Cancellable; import org.bukkit.event.Event; import org.bukkit.event.HandlerList; +/** + * Fired when a /tpa, /tpaall or /tpahere request is made. + */ public class TPARequestEvent extends Event implements Cancellable { private static final HandlerList handlers = new HandlerList(); private final CommandSource requester; diff --git a/Essentials/src/net/ess3/api/events/UserBalanceUpdateEvent.java b/Essentials/src/net/ess3/api/events/UserBalanceUpdateEvent.java index d0da97a32..fbba422cb 100644 --- a/Essentials/src/net/ess3/api/events/UserBalanceUpdateEvent.java +++ b/Essentials/src/net/ess3/api/events/UserBalanceUpdateEvent.java @@ -8,6 +8,9 @@ import org.bukkit.event.HandlerList; import java.math.BigDecimal; +/** + * Fired when a user's balance updates. + */ public class UserBalanceUpdateEvent extends Event { private static final HandlerList handlers = new HandlerList(); private final Player player; @@ -45,6 +48,11 @@ public class UserBalanceUpdateEvent extends Event { return balance; } + /** + * Override the value that the user's balance will be changed to. + * + * @param newBalance The user's new balance + */ public void setNewBalance(final BigDecimal newBalance) { Preconditions.checkNotNull(newBalance, "newBalance cannot be null."); this.balance = newBalance; @@ -58,6 +66,9 @@ public class UserBalanceUpdateEvent extends Event { return cause; } + /** + * The cause of the balance update. + */ public enum Cause { COMMAND_ECO, COMMAND_PAY, diff --git a/Essentials/src/net/ess3/api/events/UserTeleportHomeEvent.java b/Essentials/src/net/ess3/api/events/UserTeleportHomeEvent.java index 1bbdd32e2..46de07c9a 100644 --- a/Essentials/src/net/ess3/api/events/UserTeleportHomeEvent.java +++ b/Essentials/src/net/ess3/api/events/UserTeleportHomeEvent.java @@ -91,6 +91,9 @@ public class UserTeleportHomeEvent extends Event implements Cancellable { return handlers; } + /** + * The type of home location. + */ public enum HomeType { HOME, BED, diff --git a/Essentials/src/net/ess3/api/events/teleport/TeleportEvent.java b/Essentials/src/net/ess3/api/events/teleport/TeleportEvent.java index 35ddd2339..0ce330008 100644 --- a/Essentials/src/net/ess3/api/events/teleport/TeleportEvent.java +++ b/Essentials/src/net/ess3/api/events/teleport/TeleportEvent.java @@ -7,6 +7,11 @@ import org.bukkit.event.Cancellable; import org.bukkit.event.Event; import org.bukkit.event.player.PlayerTeleportEvent; +/** + * Abstract class for various teleport events. + * + * You should listen to {@link PreTeleportEvent} or {@link TeleportWarmupEvent} depending on your needs. + */ public abstract class TeleportEvent extends Event implements Cancellable { private final IUser teleporter;