Begin work on cleaning up our listeners and their Javadocs.

src/main/java/com/gmail/nossr50/datatypes/player/McMMOPlayer.java

@@ -17,6 +17,7 @@ import com.gmail.nossr50.datatypes.skills.SkillType;
 import com.gmail.nossr50.datatypes.skills.ToolType;
 import com.gmail.nossr50.datatypes.spout.huds.McMMOHud;
 import com.gmail.nossr50.events.experience.McMMOPlayerXpGainEvent;
+import com.gmail.nossr50.locale.LocaleLoader;
 import com.gmail.nossr50.party.PartyManager;
 import com.gmail.nossr50.party.ShareHandler;
 import com.gmail.nossr50.runnables.skills.AbilityDisableTask;
@@ -706,4 +707,18 @@ public class McMMOPlayer {
 
         return PerksUtils.handleXpPerks(player, xp);
     }
+
+    public void checkGodMode() {
+        if (godMode && !Permissions.mcgod(player)) {
+            toggleGodMode();
+            player.sendMessage(LocaleLoader.getString("Commands.GodMode.Forbidden"));
+        }
+    }
+
+    public void checkParty() {
+        if (inParty() && !Permissions.party(player)) {
+            removeParty();
+            player.sendMessage(LocaleLoader.getString("Party.Forbidden"));
+        }
+    }
 }

src/main/java/com/gmail/nossr50/listeners/PlayerListener.java

@@ -67,7 +67,15 @@ public class PlayerListener implements Listener {
         this.plugin = plugin;
     }
 
-
+    /**
+     * Monitor PlayerTeleportEvents.
+     * <p>
+     * These events are monitored for the purpose of setting the
+     * player's last teleportation timestamp, in order to prevent
+     * possible Acrobatics exploitation.
+     *
+     * @param event The event to monitor
+     */
     @EventHandler(priority = EventPriority.MONITOR, ignoreCancelled = true)
     public void onPlayerTeleport(PlayerTeleportEvent event) {
         Player player = event.getPlayer();
@@ -79,6 +87,15 @@ public class PlayerListener implements Listener {
         UserManager.getPlayer(player).actualizeTeleportATS();
     }
 
+    /**
+     * Handle PlayerDeathEvents at the lowest priority.
+     * <p>
+     * These events are used to modify the death message of a player when
+     * needed to correct issues potentially caused by the custom naming used
+     * for mob healthbars.
+     *
+     * @param event The event to modify
+     */
     @EventHandler(priority = EventPriority.LOWEST, ignoreCancelled = true)
     public void onPlayerDeathLowest(PlayerDeathEvent event) {
         String deathMessage = event.getDeathMessage();
@@ -87,13 +104,24 @@ public class PlayerListener implements Listener {
             return;
         }
 
-        event.setDeathMessage(MobHealthbarUtils.fixDeathMessage(deathMessage, event.getEntity()));
+        Player player = event.getEntity();
+
+        if (Misc.isNPCEntity(player)) {
+            return;
+        }
+
+        event.setDeathMessage(MobHealthbarUtils.fixDeathMessage(deathMessage, player));
     }
 
     /**
-     * Monitor PlayerDeath events.
+     * Monitor PlayerDeathEvents.
+     * <p>
+     * These events are monitored for the purpose of dealing the penalties
+     * associated with hardcore and vampirism modes. If neither of these
+     * modes are enabled, or if the player who died has hardcore bypass
+     * permissions, this handler does nothing.
      *
-     * @param event The event to watch
+     * @param event The event to monitor
      */
     @EventHandler(priority = EventPriority.MONITOR, ignoreCancelled = true)
     public void onPlayerDeathMonitor(PlayerDeathEvent event) {
@@ -101,25 +129,29 @@ public class PlayerListener implements Listener {
             return;
         }
 
-        Player player = event.getEntity();
+        Player killedPlayer = event.getEntity();
 
-        if (Misc.isNPCEntity(player) || Permissions.hardcoreBypass(player)) {
+        if (Misc.isNPCEntity(killedPlayer) || Permissions.hardcoreBypass(killedPlayer)) {
             return;
         }
 
-        Player killer = player.getKiller();
+        Player killer = killedPlayer.getKiller();
 
         if (killer != null && Config.getInstance().getHardcoreVampirismEnabled()) {
-            HardcoreManager.invokeVampirism(killer, player);
+            HardcoreManager.invokeVampirism(killer, killedPlayer);
         }
 
-        HardcoreManager.invokeStatPenalty(player);
+        HardcoreManager.invokeStatPenalty(killedPlayer);
     }
 
     /**
-     * Monitor PlayerChangedWorld events.
+     * Monitor PlayerChangedWorldEvents.
+     * <p>
+     * These events are monitored for the purpose of removing god mode or
+     * player parties if they are not allowed on the world the player has
+     * changed to.
      *
-     * @param event The event to watch
+     * @param event The event to monitor
      */
     @EventHandler(priority = EventPriority.MONITOR, ignoreCancelled = true)
     public void onPlayerWorldChange(PlayerChangedWorldEvent event) {
@@ -131,34 +163,35 @@ public class PlayerListener implements Listener {
 
         McMMOPlayer mcMMOPlayer = UserManager.getPlayer(player);
 
-        if (mcMMOPlayer.getGodMode() && !Permissions.mcgod(player)) {
-            mcMMOPlayer.toggleGodMode();
-            player.sendMessage(LocaleLoader.getString("Commands.GodMode.Forbidden"));
-        }
-
-        if (mcMMOPlayer.inParty() && !Permissions.party(player)) {
-            mcMMOPlayer.removeParty();
-            player.sendMessage(LocaleLoader.getString("Party.Forbidden"));
-        }
+        mcMMOPlayer.checkGodMode();
+        mcMMOPlayer.checkParty();
     }
 
     /**
-     * Handle PlayerDropItem events that involve modifying the event.
+     * Handle PlayerDropItemEvents at the highest priority.
+     * <p>
+     * These events are used to flag sharable dropped items, as well as
+     * remove ability buffs from pickaxes and shovels.
      *
      * @param event The event to modify
      */
     @EventHandler(priority = EventPriority.HIGHEST, ignoreCancelled = true)
     public void onPlayerDropItem(PlayerDropItemEvent event) {
         Item drop = event.getItemDrop();
+        ItemStack dropStack = drop.getItemStack();
 
-        drop.setMetadata(mcMMO.droppedItemKey, mcMMO.metadataValue);
-        SkillUtils.removeAbilityBuff(drop.getItemStack());
+        if (ItemUtils.isSharable(dropStack)) {
+            drop.setMetadata(mcMMO.droppedItemKey, mcMMO.metadataValue);
+        }
+
+        SkillUtils.removeAbilityBuff(dropStack);
     }
 
     /**
-     * Monitor PlayerFish events.
-     *
-     * @param event The event to watch
+     * Monitor PlayerFishEvents.
+     * <p>
+     * These events are monitored for the purpose of handling the various
+     * @param event The event to monitor
      */
     @EventHandler(priority = EventPriority.MONITOR, ignoreCancelled = true)
     public void onPlayerFish(PlayerFishEvent event) {
@@ -240,7 +273,7 @@ public class PlayerListener implements Listener {
         Item drop = event.getItem();
         ItemStack dropStack = drop.getItemStack();
 
-        if (!drop.hasMetadata(mcMMO.droppedItemKey) && mcMMOPlayer.inParty() && ItemUtils.isShareable(dropStack)) {
+        if (!drop.hasMetadata(mcMMO.droppedItemKey) && mcMMOPlayer.inParty() && ItemUtils.isSharable(dropStack)) {
             event.setCancelled(ShareHandler.handleItemShare(drop, mcMMOPlayer));
 
             if (event.isCancelled()) {
@@ -249,7 +282,7 @@ public class PlayerListener implements Listener {
             }
         }
 
-        if ((mcMMOPlayer.isUsingUnarmed() && ItemUtils.isShareable(dropStack)) || mcMMOPlayer.getAbilityMode(AbilityType.BERSERK)) {
+        if ((mcMMOPlayer.isUsingUnarmed() && ItemUtils.isSharable(dropStack)) || mcMMOPlayer.getAbilityMode(AbilityType.BERSERK)) {
             event.setCancelled(Unarmed.handleItemPickup(player.getInventory(), drop));
 
             if (event.isCancelled()) {

src/main/java/com/gmail/nossr50/util/ItemUtils.java

@@ -2,6 +2,7 @@ package com.gmail.nossr50.util;
 
 import org.bukkit.ChatColor;
 import org.bukkit.DyeColor;
+import org.bukkit.Material;
 import org.bukkit.inventory.ItemStack;
 import org.bukkit.inventory.meta.ItemMeta;
 
@@ -511,7 +512,11 @@ public class ItemUtils {
      * @param item Item that will get shared
      * @return True if the item can be shared.
      */
-    public static boolean isShareable(ItemStack item) {
+    public static boolean isSharable(ItemStack item) {
+        if (item == null || item.getType() == Material.AIR) {
+            return false;
+        }
+
         return isMiningDrop(item) || isWoodcuttingDrop(item) || isMobDrop(item) || isHerbalismDrop(item) || isMiscDrop(item);
     }