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;