Add Javadocs to most API classes

.checkstyle/suppressions.xml

@@ -2,5 +2,6 @@
 <!DOCTYPE suppressions PUBLIC "-//Checkstyle//DTD SuppressionFilter Configuration 1.2//EN" "http://checkstyle.org/dtds/suppressions_1_2.dtd">
 <suppressions>
     <suppress files=".*[\\/]test[\\/]java[\\/].*" checks="RequireExplicitVisibilityModifier"/>
+    <!-- TODO: don't suppress I-prefixed API interfaces under com.earth2me.essentials -->
     <suppress files="(com[\\/]earth2me[\\/]essentials[\\/]|net[\\/]ess3[\\/])(?:[^\\/]+$|(?!api)[^\\/]+[\\/])" checks="MissingJavadoc(Method|Type)"/>
 </suppressions>

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<String> getVanishedPlayers();
 

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 <i>this interface</i>.
+ *
+ * @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);
 

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.");
     }

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

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

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

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

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 <i>this interface</i>.
+ *
+ * @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

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

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;
 

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 <i>this interface</i>.
+ *
+ * @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;
 }

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

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;
 

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

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

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}.
+ * <p>
+ * 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 {
 
 }

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<String> 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.
+     *
+     * <b>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}.</b>
+     *
+     * @return
+     */
     CustomItemResolver getCustomItemResolver();
 }

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

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 <i>inside</i>
+     * a {@link ItemResolver} implementation, you <b>must</b> 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<String, ItemStack> {
 

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

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

Essentials/src/net/ess3/api/ISettings.java

@@ -1,4 +1,7 @@
 package net.ess3.api;
 
+/**
+ *
+ */
 public interface ISettings extends com.earth2me.essentials.ISettings {
 }

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

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

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;
 

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;
 

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

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

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.
+     * <p>
+     * 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);
     }

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

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,

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

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.
+ * <p>
+ * 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 <i>can</i>, 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);

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;

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;

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.
+ *
+ * <b>WARNING: The values of {@link NickChangeEvent#getAffected()} and {@link NickChangeEvent#getController()} are inverted due to a long-standing implementation bug.</b>
+ */
 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.)
+     * <b>WARNING: This method is inverted - this returns the user who <i>caused</i> the change.</b>
      *
      * @return The user who <b>caused the state change</b>.
      */
@@ -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.)
+     * <b>WARNING: This method is inverted - this returns the user who <i>was affected by</i> the change.</b>
      *
      * @return The user who <b>is affected by the state change</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);

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

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

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;

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,

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,

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;