Add Documentation to MVDestination

src/main/java/com/onarandombox/utils/CannonDestination.java

@@ -29,7 +29,7 @@ public class CannonDestination implements MVDestination {
     }
 
     @Override
-    public String getIdentifer() {
+    public String getIdentifier() {
         return "ca";
     }
 
@@ -79,11 +79,11 @@ public class CannonDestination implements MVDestination {
     }
 
     @Override
-    public void setDestination(JavaPlugin plugin, String dest) {
+    public void setDestination(JavaPlugin plugin, String destination) {
         if (!(plugin instanceof MultiverseCore)) {
             return;
         }
-        List<String> parsed = Arrays.asList(dest.split(":"));
+        List<String> parsed = Arrays.asList(destination.split(":"));
         // Need at least: e:world:x,y,z
         // OR e:world:x,y,z:pitch:yaw
         // so basically 3 or 5
@@ -91,7 +91,7 @@ public class CannonDestination implements MVDestination {
             this.isValid = false;
             return;
         }
-        if (!parsed.get(0).equalsIgnoreCase(this.getIdentifer())) {
+        if (!parsed.get(0).equalsIgnoreCase(this.getIdentifier())) {
             this.isValid = false;
             return;
         }

src/main/java/com/onarandombox/utils/ExactDestination.java

@@ -16,10 +16,10 @@ public class ExactDestination implements MVDestination {
     private Location location;
 
     @Override
-    public String getIdentifer() {
+    public String getIdentifier() {
         return "e";
     }
-    
+
     public Vector getVelocity() {
         return new Vector(0,0,0);
     }
@@ -74,11 +74,11 @@ public class ExactDestination implements MVDestination {
     }
 
     @Override
-    public void setDestination(JavaPlugin plugin, String dest) {
+    public void setDestination(JavaPlugin plugin, String destination) {
         if (!(plugin instanceof MultiverseCore)) {
             return;
         }
-        List<String> parsed = Arrays.asList(dest.split(":"));
+        List<String> parsed = Arrays.asList(destination.split(":"));
         // Need at least: e:world:x,y,z
         // OR e:world:x,y,z:pitch:yaw
         // so basically 3 or 5
@@ -87,7 +87,7 @@ public class ExactDestination implements MVDestination {
             return;
         }
 
-        if (!parsed.get(0).equalsIgnoreCase(this.getIdentifer())) {
+        if (!parsed.get(0).equalsIgnoreCase(this.getIdentifier())) {
             this.isValid = false;
             return;
         }

src/main/java/com/onarandombox/utils/InvalidDestination.java

@@ -9,12 +9,12 @@ import org.bukkit.util.Vector;
 public class InvalidDestination implements MVDestination {
 
     @Override
-    public String getIdentifer() {
+    public String getIdentifier() {
         return "i";
     }
 
     @Override
-    public boolean isThisType(JavaPlugin plugin, String dest) {
+    public boolean isThisType(JavaPlugin plugin, String destination) {
         return false;
     }
 
@@ -29,7 +29,7 @@ public class InvalidDestination implements MVDestination {
     }
 
     @Override
-    public void setDestination(JavaPlugin plugin, String dest) {
+    public void setDestination(JavaPlugin plugin, String destination) {
         // Nothing needed, it's invalid.
     }
 

src/main/java/com/onarandombox/utils/MVDestination.java

@@ -5,16 +5,128 @@ import org.bukkit.entity.Entity;
 import org.bukkit.plugin.java.JavaPlugin;
 import org.bukkit.util.Vector;
 
+/**
+ * A destination API for Multiverse
+ * Any plugin can add these to MV and when they are, any action that uses them (portals, MVTP, etc.) can use them!
+ * @author fernferret
+ */
 public interface MVDestination {
-    public String getIdentifer();
-    public boolean isThisType(JavaPlugin plugin, String dest);
-    public Location getLocation(Entity e);
-    public boolean isValid();
-    public void setDestination(JavaPlugin plugin, String dest);
-    public String getType();
-    public String getName();
-    public String toString();
-    public String getRequiredPermission();
+    /**
+     * Returns the identifier or prefix that is required for this destination.
+     *
+     * Portals have a prefix of "p" for example and OpenWarp (third party plugin) uses "ow". This is derived from a
+     * hash and cannot have duplicate values. Read that as your plugin cannot use 'p' because it's already used.
+     * Please check the wiki when adding a custom destination!
+     *
+     * @return The identifier or prefix that is required for this destination.
+     */
+    public String getIdentifier();
+
+    /**
+     * Allows you to determine if a Destination is valid for the type it thinks it is.
+     *
+     * An example of this would be the exact destination. A valid string would be: e:0,0,0 where an invalid one would
+     * be e:1:2:3. The first string would return true the second would return false. This is simply a convenience method
+     * and does not even NEED to be called, but it's highly recommended if you're teleporting, but it's mainly for
+     * Multiverse Internal use.
+     *
+     * @param plugin The plugin who the type belongs to.
+     * @param destination The destination string. ex: p:MyPortal:nw
+     * @return True if the destination is valid, false if not.
+     */
+    public boolean isThisType(JavaPlugin plugin, String destination);
+
+    /**
+     * Returns the location a specific entity will spawn at.
+     *
+     * To just retrieve the location as it is stored you can just pass null, but be warned some destinations may return
+     * null back to you if you do this. It is always safer to pass an actual entity. This is used so things like
+     * minecarts can be teleported.
+     *
+     * Do not forget to use {@link #getVelocity()} as destinations can use this too!
+     *
+     * @param entity The entity to be teleported.
+     * @return The location of the entity.
+     */
+    public Location getLocation(Entity entity);
+
+    /**
+     * Returns the velocity vector for this destination.
+     *
+     * Plugins wishing to fully support MVDestinations MUST implement this.
+     *
+     * @return A vector representing the speed/direction the player should travel when arriving
+     */
     public Vector getVelocity();
+
+    /**
+     * Sets the destination string.
+     *
+     * This should be used when you want to tell this destination object about a change in where it should take people.
+     * The destination param should be match the result from {@link #getIdentifier()}. A valid example would be that if
+     * {@link #getIdentifier()} returned "ow" our destination string could be "ow:TownCenter" but could not be
+     * "p:HomePortal"
+     *
+     * @param plugin The plugin who the type belongs to.
+     * @param destination The destination string. ex: p:MyPortal:nw
+     */
+    public void setDestination(JavaPlugin plugin, String destination);
+
+    /**
+     * Returns true if the destination is valid and players will be taken to it.
+     *
+     * Even if destinations are in the correct format (p:MyPortal) MyPortal may not exist, and therefore this would
+     * return false.
+     *
+     * @return True if the destination is valid; false if not.
+     */
+    public boolean isValid();
+
+    /**
+     * Gives you a general friendly description of the type of destination.
+     *
+     * For example, the PlayerDestination sets this to "Player". You can use this to show where a player will be taken.
+     *
+     * @return A friendly string description of the type of destination.
+     */
+    public String getType();
+
+    /**
+     * Gives you a specific name of the destination.
+     *
+     * For example, the PlayerDestination sets this to The Player's Name.
+     *
+     * @return A friendly string stating the name of the destination.
+     */
+    public String getName();
+
+    /**
+     * Returns a string that can easily be saved in the config that contains all the details needed to rebuild this
+     * destination.
+     *
+     * ex: e:0,0,0:50:50
+     *
+     * @return The savable config string.
+     */
+    public String toString();
+
+    /**
+     * Returns the permissions string required to go here.
+     *
+     * ex: multiverse.access.world
+     *
+     * NOTE: This is NOT the permission to use the teleport command.
+     *
+     * @return the permissions string required to go here.
+     */
+    public String getRequiredPermission();
+
+    /**
+     * Should the Multiverse SafeTeleporter be used?
+     *
+     * If not, MV will blindly take people to the location specified.
+     *
+     * @return True if the SafeTeleporter will be used, false if not.
+     */
     public boolean useSafeTeleporter();
 }

src/main/java/com/onarandombox/utils/PlayerDestination.java

@@ -12,13 +12,13 @@ public class PlayerDestination implements MVDestination {
     private JavaPlugin plugin;
 
     @Override
-    public String getIdentifer() {
+    public String getIdentifier() {
         return "pl";
     }
 
     @Override
-    public boolean isThisType(JavaPlugin plugin, String dest) {
-        String[] items = dest.split(":");
+    public boolean isThisType(JavaPlugin plugin, String destination) {
+        String[] items = destination.split(":");
         if (items.length != 2) {
             return false;
         }
@@ -50,8 +50,8 @@ public class PlayerDestination implements MVDestination {
     }
 
     @Override
-    public void setDestination(JavaPlugin plugin, String dest) {
-        String[] items = dest.split(":");
+    public void setDestination(JavaPlugin plugin, String destination) {
+        String[] items = destination.split(":");
         if (items.length != 2) {
             this.isValid = false;
         }

src/main/java/com/onarandombox/utils/WorldDestination.java

@@ -15,7 +15,7 @@ public class WorldDestination implements MVDestination {
     String direction = "";
 
     @Override
-    public String getIdentifer() {
+    public String getIdentifier() {
         return "w";
     }
 
@@ -44,17 +44,17 @@ public class WorldDestination implements MVDestination {
     public Location getLocation(Entity e) {
         Location spawnLoc = getAcurateSpawnLocation(e, this.world);
         if (this.yaw >= 0) {
-            // Only modify the yaw if its set. 
+            // Only modify the yaw if its set.
             spawnLoc.setYaw(this.yaw);
         }
         return spawnLoc;
     }
-    
+
     private Location getAcurateSpawnLocation(Entity e, MVWorld world) {
         if(world != null) {
             return world.getSpawnLocation();
         } else {
-            return e.getWorld().getSpawnLocation().add(.5, 0, .5);    
+            return e.getWorld().getSpawnLocation().add(.5, 0, .5);
         }
     }
 
@@ -64,8 +64,8 @@ public class WorldDestination implements MVDestination {
     }
 
     @Override
-    public void setDestination(JavaPlugin plugin, String dest) {
-        String[] items = dest.split(":");
+    public void setDestination(JavaPlugin plugin, String destination) {
+        String[] items = destination.split(":");
         if (items.length > 3) {
             isValid = false;
             return;
@@ -102,7 +102,7 @@ public class WorldDestination implements MVDestination {
     @Override
     public String toString() {
         if(direction.length() > 0 && yaw >= 0) {
-            return this.world.getCBWorld().getName() + ":"+this.direction;            
+            return this.world.getCBWorld().getName() + ":"+this.direction;
         }
         return this.world.getCBWorld().getName();
     }