Merge pull request #107 from D3v1s0m/2.X

more Javadocs

api/src/main/java/lol/pyr/znpcsplus/api/NpcApi.java

@@ -5,9 +5,31 @@ import lol.pyr.znpcsplus.api.npc.NpcRegistry;
 import lol.pyr.znpcsplus.api.npc.NpcTypeRegistry;
 import lol.pyr.znpcsplus.api.skin.SkinDescriptorFactory;
 
+/**
+ * Main API class for ZNPCsPlus.
+ */
 public interface NpcApi {
+    /**
+     * Gets the NPC registry.
+     * @return the NPC registry
+     */
     NpcRegistry getNpcRegistry();
+
+    /**
+     * Gets the NPC type registry.
+     * @return the NPC type registry
+     */
     NpcTypeRegistry getNpcTypeRegistry();
+
+    /**
+     * Gets the entity property registry.
+     * @return the entity property registry
+     */
     EntityPropertyRegistry getPropertyRegistry();
+
+    /**
+     * Gets the skin descriptor factory.
+     * @return the skin descriptor factory
+     */
     SkinDescriptorFactory getSkinDescriptorFactory();
 }

api/src/main/java/lol/pyr/znpcsplus/api/NpcApiProvider.java

@@ -4,6 +4,9 @@ import org.bukkit.Bukkit;
 import org.bukkit.plugin.Plugin;
 import org.bukkit.plugin.ServicePriority;
 
+/**
+ * Provider for the registered api instance
+ */
 public class NpcApiProvider {
     private static NpcApi api = null;
 

api/src/main/java/lol/pyr/znpcsplus/api/event/NpcDespawnEvent.java

@@ -6,9 +6,17 @@ import org.bukkit.entity.Player;
 import org.bukkit.event.Cancellable;
 import org.bukkit.event.HandlerList;
 
+/**
+ * Event called when an NPC is despawned for a player
+ * Note: This event is async
+ */
 public class NpcDespawnEvent extends CancellableNpcEvent implements Cancellable {
     private static final HandlerList handlers = new HandlerList();
 
+    /**
+     * @param player The player involved in the event
+     * @param entry The NPC entry involved in the event
+     */
     public NpcDespawnEvent(Player player, NpcEntry entry) {
         super(player, entry);
     }

api/src/main/java/lol/pyr/znpcsplus/api/event/NpcInteractEvent.java

@@ -7,11 +7,20 @@ import org.bukkit.entity.Player;
 import org.bukkit.event.Cancellable;
 import org.bukkit.event.HandlerList;
 
+/**
+ * Event called when an NPC is interacted with by a player
+ * Note: This event is async
+ */
 public class NpcInteractEvent extends CancellableNpcEvent implements Cancellable {
     private static final HandlerList handlers = new HandlerList();
 
     private final InteractionType clickType;
 
+    /**
+     * @param player The player involved in the event
+     * @param entry The NPC entry involved in the event
+     * @param clickType The type of interaction. See {@link InteractionType}
+     */
     public NpcInteractEvent(Player player, NpcEntry entry, InteractionType clickType) {
         super(player, entry);
         this.clickType = clickType;
@@ -22,6 +31,10 @@ public class NpcInteractEvent extends CancellableNpcEvent implements Cancellable
         return handlers;
     }
 
+    /**
+     * Returns the type of interaction. See {@link InteractionType}
+     * @return The type of interaction
+     */
     public InteractionType getClickType() {
         return clickType;
     }

api/src/main/java/lol/pyr/znpcsplus/api/event/NpcSpawnEvent.java

@@ -6,9 +6,17 @@ import org.bukkit.entity.Player;
 import org.bukkit.event.Cancellable;
 import org.bukkit.event.HandlerList;
 
+/**
+ * Event called when an NPC is spawned for a player
+ * Note: This event is async
+ */
 public class NpcSpawnEvent extends CancellableNpcEvent implements Cancellable {
     private static final HandlerList handlers = new HandlerList();
 
+    /**
+     * @param player The player involved in the event
+     * @param entry The NPC entry involved in the event
+     */
     public NpcSpawnEvent(Player player, NpcEntry entry) {
         super(player, entry);
     }

api/src/main/java/lol/pyr/znpcsplus/api/event/util/CancellableNpcEvent.java

@@ -4,9 +4,16 @@ import lol.pyr.znpcsplus.api.npc.NpcEntry;
 import org.bukkit.entity.Player;
 import org.bukkit.event.Cancellable;
 
+/**
+ * Base class for all NPC events that can be cancelled
+ */
 public abstract class CancellableNpcEvent extends NpcEvent implements Cancellable {
     private boolean cancelled = false;
 
+    /**
+     * @param player The player involved in the event
+     * @param entry The NPC entry involved in the event
+     */
     public CancellableNpcEvent(Player player, NpcEntry entry) {
         super(player, entry);
     }

api/src/main/java/lol/pyr/znpcsplus/api/event/util/NpcEvent.java

@@ -5,24 +5,43 @@ import lol.pyr.znpcsplus.api.npc.NpcEntry;
 import org.bukkit.entity.Player;
 import org.bukkit.event.Event;
 
+/**
+ * Base class for all NPC events
+ */
 public abstract class NpcEvent extends Event {
     private final NpcEntry entry;
     private final Player player;
 
+    /**
+     * @param player The player involved in the event
+     * @param entry The NPC entry involved in the event
+     */
     public NpcEvent(Player player, NpcEntry entry) {
         super(true); // All events are async since 99% of the plugin is async
         this.entry = entry;
         this.player = player;
     }
 
+    /**
+     * Returns the player involved in the event
+     * @return The player involved in the event
+     */
     public Player getPlayer() {
         return player;
     }
 
+    /**
+     * Returns the NPC entry involved in the event
+     * @return The NPC entry involved in the event
+     */
     public NpcEntry getEntry() {
         return entry;
     }
 
+    /**
+     * Returns the NPC involved in the event
+     * @return The NPC involved in the event
+     */
     public Npc getNpc() {
         return entry.getNpc();
     }

api/src/main/java/lol/pyr/znpcsplus/api/hologram/Hologram.java

@@ -1,10 +1,44 @@
 package lol.pyr.znpcsplus.api.hologram;
 
+/**
+ * Represents a hologram
+ */
 public interface Hologram {
+    /**
+     * Adds a line to the hologram
+     * Note: to add an item line, pass "item:<item>" as the line
+     * @param line The line to add
+     */
     void addLine(String line);
+
+    /**
+     * Gets a line from the hologram
+     * @param index The index of the line to get
+     * @return The line at the index
+     */
     String getLine(int index);
+
+    /**
+     * Removes a line from the hologram
+     * @param index The index of the line to remove
+     */
     void removeLine(int index);
+
+    /**
+     * Clears all lines from the hologram
+     */
     void clearLines();
+
+    /**
+     * Inserts a line into the hologram
+     * @param index The index to insert the line at
+     * @param line The line to insert
+     */
     void insertLine(int index, String line);
+
+    /**
+     * Gets the number of lines in the hologram
+     * @return The number of lines in the hologram
+     */
     int lineCount();
 }

api/src/main/java/lol/pyr/znpcsplus/api/interaction/InteractionAction.java

@@ -4,12 +4,35 @@ import org.bukkit.entity.Player;
 
 import java.util.UUID;
 
+/**
+ * Base class for all NPC interactions
+ */
 public abstract class InteractionAction {
+    /**
+     * The unique ID of this interaction
+     */
     private final UUID id;
+
+    /**
+     * The cooldown of this interaction in seconds
+     */
     private final long cooldown;
+
+    /**
+     * The delay of this interaction in ticks
+     */
     private final long delay;
+
+    /**
+     * The type of this interaction
+     */
     private final InteractionType interactionType;
 
+    /**
+     * @param cooldown The cooldown of this interaction in seconds
+     * @param delay The delay of this interaction in ticks
+     * @param interactionType The type of this interaction
+     */
     protected InteractionAction(long cooldown, long delay, InteractionType interactionType) {
         this.interactionType = interactionType;
         this.id = UUID.randomUUID();
@@ -17,21 +40,37 @@ public abstract class InteractionAction {
         this.delay = delay;
     }
 
+    /**
+     * @return The unique ID of this interaction
+     */
     public UUID getUuid() {
         return id;
     }
 
+    /**
+     * @return The cooldown of this interaction in seconds
+     */
     public long getCooldown() {
         return cooldown;
     }
 
+    /**
+     * @return The delay of this interaction in ticks
+     */
     public long getDelay() {
         return delay;
     }
 
+    /**
+     * @return The type of this interaction
+     */
     public InteractionType getInteractionType() {
         return interactionType;
     }
 
+    /**
+     * Runs this interaction
+     * @param player The player that triggered this interaction
+     */
     public abstract void run(Player player);
 }

api/src/main/java/lol/pyr/znpcsplus/api/interaction/InteractionType.java

@@ -1,5 +1,11 @@
 package lol.pyr.znpcsplus.api.interaction;
 
+/**
+ * The type of interaction
+ * ANY_CLICK: Any click type
+ * LEFT_CLICK: Only left clicks
+ * RIGHT_CLICK: Only right clicks
+ */
 public enum InteractionType {
     ANY_CLICK,
     LEFT_CLICK,

api/src/main/java/lol/pyr/znpcsplus/api/npc/Npc.java

@@ -10,22 +10,107 @@ import org.bukkit.entity.Player;
 import java.util.List;
 import java.util.UUID;
 
+/**
+ * Base class for all NPCs
+ */
 public interface Npc extends PropertyHolder {
+    /**
+     * Sets the npc type of this NPC
+     * @param type The {@link NpcType} to set
+     */
     void setType(NpcType type);
+
+    /**
+     * @return The {@link NpcType} of this NPC
+     */
     NpcType getType();
+
+    /**
+     * Gets the location of this NPC
+     * @return The {@link NpcLocation} of this NPC
+     */
     NpcLocation getLocation();
+
+    /**
+     * Sets the location of this NPC
+     * @param location The {@link NpcLocation} to set
+     */
     void setLocation(NpcLocation location);
+
+    /**
+     * Gets the hologram of this NPC
+     * @return The {@link Hologram} of this NPC
+     */
     Hologram getHologram();
+
+    /**
+     * Sets if the npc is enabled or not, i.e. if it should be visible to players
+     * @param enabled If the npc should be enabled
+     */
     void setEnabled(boolean enabled);
+
+    /**
+     * Gets if the npc is enabled or not, i.e. if it should be visible to players
+     * @return If the npc is enabled or not
+     */
     boolean isEnabled();
+
+    /**
+     * Gets the unique ID of this NPC
+     * @return The unique ID of this NPC
+     */
     UUID getUuid();
+
+    /**
+     * Gets the {@link World} this NPC is in
+     * Note: can be null if the world is unloaded or does not exist
+     * @return The {@link World} this NPC is in
+     */
     World getWorld();
+
+    /**
+     * Gets the list of actions for this NPC
+     * @return The {@link List} of {@link InteractionAction}s for this NPC
+     */
     List<? extends InteractionAction> getActions();
+
+    /**
+     * Gets if this NPC is visible to a player
+     * @param player The {@link Player} to check
+     * @return If this NPC is visible to the player
+     */
     boolean isVisibleTo(Player player);
+
+    /**
+     * Hides this NPC from a player
+     * @param player The {@link Player} to hide from
+     */
     void hide(Player player);
+
+    /**
+     * Shows this NPC to a player
+     * @param player The {@link Player} to show to
+     */
     void show(Player player);
+
+    /**
+     * Respawns this NPC for a player
+     * @param player The {@link Player} to respawn for
+     */
     void respawn(Player player);
 
+    /**
+     * Sets the head rotation of this NPC for a player
+     * @param player The {@link Player} to set the head rotation for
+     * @param yaw The yaw to set
+     * @param pitch The pitch to set
+     */
     void setHeadRotation(Player player, float yaw, float pitch);
+
+    /**
+     * Sets the head rotation of this NPC for all players/viewers
+     * @param yaw The yaw to set
+     * @param pitch The pitch to set
+     */
     void setHeadRotation(float yaw, float pitch);
 }

api/src/main/java/lol/pyr/znpcsplus/api/npc/NpcEntry.java

@@ -1,17 +1,56 @@
 package lol.pyr.znpcsplus.api.npc;
 
+/**
+ * Base class for all NPC entries
+ * An NPC entry is a wrapper around an NPC that contains additional information
+ */
 public interface NpcEntry {
+    /**
+     * Gets the ID of this NPC entry
+     * @return The ID of this NPC entry
+     */
     String getId();
+    /**
+     * Gets the NPC of this NPC entry
+     * @return The {@link Npc} of this NPC entry
+     */
     Npc getNpc();
 
+    /**
+     * Gets if this NPC entry is processed or not
+     * @return If this NPC entry is processed or not
+     */
     boolean isProcessed();
+    /**
+     * Sets if this NPC entry is processed or not
+     * @param value If this NPC entry is processed or not
+     */
     void setProcessed(boolean value);
 
+    /**
+     * @return If this NPC entry SHOULD be saved into the storage or not
+     */
     boolean isSave();
+    /**
+     * Sets if this NPC should be saved or not
+     * @param value If this NPC entry should be saved or not
+     */
     void setSave(boolean value);
 
+    /**
+     * Gets if this NPC can be modified by commands
+     * @return {@code true} if this NPC can be modified by commands, {@code false} otherwise
+     */
     boolean isAllowCommandModification();
+    /**
+     * Sets if this NPC can be modified by commands
+     * @param value {@code true} if this NPC can be modified by commands, {@code false} otherwise
+     */
     void setAllowCommandModification(boolean value);
 
+    /**
+     * Enables everything for this NPC entry
+     * That is, it makes the NPC processed, saveable, and allows command modification
+     */
     void enableEverything();
 }

api/src/main/java/lol/pyr/znpcsplus/api/npc/NpcRegistry.java

@@ -6,13 +6,62 @@ import org.bukkit.World;
 import java.util.Collection;
 import java.util.UUID;
 
+/**
+ * Base class for all NPC registries
+ */
 public interface NpcRegistry {
+
+    /**
+     * Gets all NPC entries
+     * @return All NPC entries
+     */
     Collection<? extends NpcEntry> getAll();
+
+    /**
+     * Gets all NPC IDs
+     * @return All NPC IDs
+     */
     Collection<String> getAllIds();
+
+    /**
+     * Gets all NPC entries that are player made
+     * @return All player made NPC entries
+     */
     Collection<? extends NpcEntry> getAllPlayerMade();
+
+    /**
+     * Gets IDs of all player made NPCs
+     * @return IDs of all player made NPCs
+     */
     Collection<String> getAllPlayerMadeIds();
+
+    /**
+     * Creates a new NPC entry
+     * @param id The ID of the NPC entry
+     * @param world The {@link World} of the NPC entry
+     * @param type The {@link NpcType} of the NPC entry
+     * @param location The {@link NpcLocation} of the NPC entry
+     * @return
+     */
     NpcEntry create(String id, World world, NpcType type, NpcLocation location);
+
+    /**
+     * Gets an NPC entry by its ID
+     * @param id The ID of the NPC entry
+     * @return The NPC entry
+     */
     NpcEntry getById(String id);
+
+    /**
+     * Gets an NPC entry by its UUID
+     * @param uuid The UUID of the NPC entry
+     * @return The NPC entry
+     */
     NpcEntry getByUuid(UUID uuid);
+
+    /**
+     * Deletes an NPC entry by its ID
+     * @param id The ID of the NPC entry
+     */
     void delete(String id);
 }

api/src/main/java/lol/pyr/znpcsplus/api/npc/NpcType.java

@@ -4,8 +4,26 @@ import lol.pyr.znpcsplus.api.entity.EntityProperty;
 
 import java.util.Set;
 
+/**
+ * Represents a type of NPC.
+ * This defines the {@link org.bukkit.entity.EntityType} of the NPC, as well as the properties that are allowed to be set on the NPC.
+ */
 public interface NpcType {
+    /**
+     * The name of the NPC type.
+     * @return The name of the NPC type.
+     */
     String getName();
+
+    /**
+     * The offset of the hologram above the NPC.
+     * @return the offset
+     */
     double getHologramOffset();
+
+    /**
+     * Set of properties that are allowed to be set on the NPC.
+     * @return allowed properties
+     */
     Set<EntityProperty<?>> getAllowedProperties();
 }

api/src/main/java/lol/pyr/znpcsplus/api/npc/NpcTypeRegistry.java

@@ -2,7 +2,18 @@ package lol.pyr.znpcsplus.api.npc;
 
 import java.util.Collection;
 
+/**
+ * Base for NpcType registries.
+ */
 public interface NpcTypeRegistry {
+    /**
+     * Gets a NPC type by name.
+     * @param name The name of the NPC type.
+     */
     NpcType getByName(String name);
+
+    /**
+     * Gets all NPC types.
+     */
     Collection<NpcType> getAll();
 }

api/src/main/java/lol/pyr/znpcsplus/api/skin/SkinDescriptorFactory.java

@@ -2,6 +2,9 @@ package lol.pyr.znpcsplus.api.skin;
 
 import java.net.URL;
 
+/**
+ * Factory for creating skin descriptors.
+ */
 public interface SkinDescriptorFactory {
     SkinDescriptor createMirrorDescriptor();
     SkinDescriptor createRefreshingDescriptor(String playerName);