More work on the API

8 files changed, 126 insertions, 31 deletions

diff --git a/Essentials/src/net/ess3/api/IPlugin.java b/Essentials/src/net/ess3/api/IPlugin.java
index 1d78e13e5..33091c24f 100644
--- a/Essentials/src/net/ess3/api/IPlugin.java
+++ b/Essentials/src/net/ess3/api/IPlugin.java
@@ -12,7 +12,7 @@ public interface IPlugin extends Plugin
 	/**
 	 * Get an instance of essentials
 	 *
-	 * @return
+	 * @return the instance
 	 */
 	IEssentials getEssentials();
 
diff --git a/Essentials/src/net/ess3/api/ISettings.java b/Essentials/src/net/ess3/api/ISettings.java
index eec3df7ce..4be8e9d27 100644
--- a/Essentials/src/net/ess3/api/ISettings.java
+++ b/Essentials/src/net/ess3/api/ISettings.java
@@ -7,20 +7,23 @@ import net.ess3.storage.IStorageObjectHolder;
 public interface ISettings extends IStorageObjectHolder<Settings>
 {
 	/**
+	 * Used to get the locale string
 	 *
-	 * @return
+	 * @return the current locale string (i.e. en_US)
 	 */
 	String getLocale();
 
 	/**
+	 * Used to check if debug mode is enabled
 	 *
-	 * @return
+	 * @return true if debug is enabled
 	 */
 	boolean isDebug();
 
 	/**
+	 * Used to set debug mode
 	 *
-	 * @param b **TODO: rename this, "b" is a terrible name**
+	 * @param set
 	 */
-	void setDebug(boolean b);
+	void setDebug(boolean set);
 }
diff --git a/Essentials/src/net/ess3/api/IUserMap.java b/Essentials/src/net/ess3/api/IUserMap.java
index 47c7631f8..de891db09 100644
--- a/Essentials/src/net/ess3/api/IUserMap.java
+++ b/Essentials/src/net/ess3/api/IUserMap.java
@@ -10,100 +10,117 @@ import org.bukkit.entity.Player;
 public interface IUserMap extends IReload
 {
 	/**
+	 * Used to check if a user exists (they exist if they have userdata)
 	 *
-	 * @param name
-	 * @return
+	 * @param name the name of the user to check
+	 * @return true if the user exists, false if not
 	 */
 	boolean userExists(final String name);
 
 	/**
+	 * Used to get the user associated with the given Player object
 	 *
-	 * @param player
-	 * @return
+	 * @param player the Player object
+	 * @return the User object
 	 */
 	IUser getUser(final Player player);
 
 	/**
+	 * Used to get the user associated with the given name
 	 *
-	 * @param playerName
-	 * @return
+	 * @param playerName the name of the player
+	 * @return the User object
 	 */
 	IUser getUser(final String playerName);
 
 	/**
+	 * Used to remove a user from the userMap
 	 *
-	 * @param name
-	 * @throws InvalidNameException
+	 * @param name the name of the user to remove
+	 * @throws InvalidNameException if the name does not match any user in the UserMap
 	 */
 	void removeUser(final String name) throws InvalidNameException;
 
 	/**
+	 * Gets a set of all the unique users in the UserMap
 	 *
-	 * @return
+	 * @return the Users
 	 */
 	Set<String> getAllUniqueUsers();
 
 	/**
+	 * Gets the number of unique users in the UserMap
 	 *
-	 * @return
+	 * @return the number of unique users
 	 */
 	int getUniqueUsers();
 
 	/**
+	 * Used to get the file of the given user
 	 *
-	 * @param name
-	 * @return
+	 * @param name the name of the user
+	 * @return the file
 	 * @throws InvalidNameException
 	 */
 	File getUserFile(final String name) throws InvalidNameException;
 
 	/**
+	 * Used to match a user to a given name
 	 * This method never returns null and includes hidden players.
 	 *
-	 * @param name
-	 * @param includeOffline
-	 * @return
+	 * @param name the name to match
+	 * @param includeOffline set to true to check offline users as well, false if not
+	 * @return the matched user
 	 * @throws TooManyMatchesException if more than one player is found matching the name
 	 * @throws PlayerNotFoundException if the player matching the name is not found
 	 */
 	IUser matchUser(final String name, final boolean includeOffline) throws TooManyMatchesException, PlayerNotFoundException;
 
 	/**
+	 * Used to match a user to a given name
 	 * This method never returns null and is for online players only.
 	 *
-	 * @param name
+	 * @param name the name to match
 	 * @param requester Can be null, if the requester is the console
-	 * @return
+	 * @return the matched user
 	 * @throws TooManyMatchesException if more than one player is found matching the name
 	 * @throws PlayerNotFoundException if the player matching the name is not found
 	 */
 	IUser matchUserExcludingHidden(final String name, final Player requester) throws TooManyMatchesException, PlayerNotFoundException;
 
 	/**
+	 * Used to match multiple users
+	 * This method never returns null and includes hidden players.
 	 *
-	 * @param name
-	 * @param includeOffline
-	 * @return
+	 * @param name the name to match
+	 * @param includeOffline set to true to check offline users as well, false if not
+	 * @return the matched user(s)
 	 */
 	Set<IUser> matchUsers(final String name, final boolean includeOffline);
 
 	/**
+	 * Used to match multiple users
+	 * This method never returns null and is for online players only.
 	 *
-	 * @param name
-	 * @param requester
-	 * @return
+	 * @param name the name to match
+	 * @param requester Can be null, if the requester is the console
+	 * @return the matched user(s)
 	 */
 	Set<IUser> matchUsersExcludingHidden(final String name, final Player requester);
 
 	/**
+	 * Used to add a player to the map of pre-joined players
+	 * **TODO: we shouldn't be using player objects here**
 	 *
-	 * @param player
+	 * @param player the player to add
 	 */
 	void addPrejoinedPlayer(Player player);
 
 	/**
+	 * Used to remove a player from the map of pre-joined players
+	 * **TODO: we shouldn't be using player objects here**
 	 *
-	 * @param player
+	 * @param player the player to remove
 	 */
 	void removePrejoinedPlayer(Player player);
 }
diff --git a/Essentials/src/net/ess3/user/UserMap.java b/Essentials/src/net/ess3/user/UserMap.java
index 9df31e543..9421b0d62 100644
--- a/Essentials/src/net/ess3/user/UserMap.java
+++ b/Essentials/src/net/ess3/user/UserMap.java
@@ -15,7 +15,7 @@ import org.bukkit.entity.Player;
 
 public class UserMap extends StorageObjectMap<IUser> implements IUserMap
 {
-	private final Map<String, Player> prejoinedPlayers = new HashMap<String, Player>();
+	private final Map<String, Player> prejoinedPlayers = new HashMap<String, Player>(); //TODO: We shouldn't be using a player object here
 
 	public UserMap(final IEssentials ess)
 	{
diff --git a/EssentialsAntiBuild/src/net/ess3/antibuild/IAntiBuild.java b/EssentialsAntiBuild/src/net/ess3/antibuild/IAntiBuild.java
index 1cbd4df6e..0e90bc75f 100644
--- a/EssentialsAntiBuild/src/net/ess3/antibuild/IAntiBuild.java
+++ b/EssentialsAntiBuild/src/net/ess3/antibuild/IAntiBuild.java
@@ -5,9 +5,21 @@ import org.bukkit.plugin.Plugin;
 
 public interface IAntiBuild extends Plugin
 {
+	/**
+	 *
+	 * @return
+	 */
 	EssentialsConnect getEssentialsConnect();
 
+	/**
+	 *
+	 * @return
+	 */
 	AntiBuildHolder getSettings();
 
+	/**
+	 *
+	 * @param settings
+	 */
 	void setSettings(AntiBuildHolder settings);
 }
diff --git a/EssentialsProtect/src/net/ess3/protect/IProtect.java b/EssentialsProtect/src/net/ess3/protect/IProtect.java
index de3dbc3fa..8e4bf5895 100644
--- a/EssentialsProtect/src/net/ess3/protect/IProtect.java
+++ b/EssentialsProtect/src/net/ess3/protect/IProtect.java
@@ -5,9 +5,21 @@ import org.bukkit.plugin.Plugin;
 
 public interface IProtect extends Plugin
 {
+	/**
+	 *
+	 * @return
+	 */
 	EssentialsConnect getEssentialsConnect();
 
+	/**
+	 *
+	 * @return
+	 */
 	ProtectHolder getSettings();
 
+	/**
+	 *
+	 * @param settings
+	 */
 	void setSettings(ProtectHolder settings);
 }
diff --git a/EssentialsSigns/src/net/ess3/signs/ISignsPlugin.java b/EssentialsSigns/src/net/ess3/signs/ISignsPlugin.java
index 7ab6f0dfe..d3483d392 100644
--- a/EssentialsSigns/src/net/ess3/signs/ISignsPlugin.java
+++ b/EssentialsSigns/src/net/ess3/signs/ISignsPlugin.java
@@ -3,5 +3,9 @@ package net.ess3.signs;
 
 public interface ISignsPlugin
 {
+	/**
+	 *
+	 * @return
+	 */
 	SignsConfigHolder getSettings();
 }
diff --git a/EssentialsXMPP/src/net/ess3/xmpp/IEssentialsXMPP.java b/EssentialsXMPP/src/net/ess3/xmpp/IEssentialsXMPP.java
index 789ccddc9..bf221a370 100644
--- a/EssentialsXMPP/src/net/ess3/xmpp/IEssentialsXMPP.java
+++ b/EssentialsXMPP/src/net/ess3/xmpp/IEssentialsXMPP.java
@@ -8,21 +8,68 @@ import org.bukkit.plugin.Plugin;
 
 public interface IEssentialsXMPP extends Plugin
 {
+	/**
+	 *
+	 * @param user
+	 * @return
+	 */
 	String getAddress(final CommandSender user);
 
+	/**
+	 *
+	 * @param name
+	 * @return
+	 */
 	String getAddress(final String name);
 
+	/**
+	 *
+	 * @return
+	 */
 	List<String> getSpyUsers();
 
+	/**
+	 *
+	 * @param address
+	 * @return
+	 */
 	IUser getUserByAddress(final String address);
 
+	/**
+	 *
+	 * @param user
+	 * @param message
+	 * @return
+	 */
 	boolean sendMessage(final CommandSender user, final String message);
 
+	/**
+	 *
+	 * @param address
+	 * @param message
+	 * @return
+	 */
 	boolean sendMessage(final String address, final String message);
 
+	/**
+	 *
+	 * @param user
+	 * @param address
+	 */
 	void setAddress(final CommandSender user, final String address);
 
+	/**
+	 *
+	 * @param user
+	 * @return
+	 */
 	boolean toggleSpy(final CommandSender user);
 
+	/**
+	 *
+	 * @param sender
+	 * @param message
+	 * @param xmppAddress
+	 */
 	void broadcastMessage(final IUser sender, final String message, final String xmppAddress);
 }