Merge pull request #11 from whimc/adding-documentation

Adding documentation

README.md

@@ -1,10 +1,49 @@
 # WHIMC-PositionTracker
 [![GitHub release (latest by date)](https://img.shields.io/github/v/release/whimc/Position-Tracker?label=download&logo=github)](https://github.com/whimc/Position-Tracker/releases/latest)
 
-Track player positions to a database
+PositionTracker is a Minecraft plugin that tracks player positions and stores them in an SQL database.
+
+---
 
 ## Building
 Build the source with Maven:
 ```
 $ mvn install
-```
+```
+
+---
+
+## Configuration
+
+`debug` is a `boolean` that toggles debug messages in the console.
+
+### MySQL
+| Key	           | Type	   | Description                     |
+|------------------|-----------|---------------------------------|
+| `mysql.host`	   | `string`  | The host of the database        |
+| `mysql.port`	   | `integer` | The port of the database        |
+| `mysql.database` | `string`  | The name of the database to use |
+| `mysql.username` | `string`  | Username for credentials        |
+| `mysql.password` | `string`  | Password for credentials        |
+
+#### Example
+```yaml
+debug: false
+mysql:
+    host: localhost
+    port: 3306
+    database: minecraft
+    username: user
+    password: pass
+```
+
+---
+
+## Commands
+| Command	                | Description                          |
+|---------------------------|--------------------------------------|
+| `/positiontracker status`	| Get the status of the tracker        |
+| `/positiontracker debug`  | Toggle the debug messages in console |
+| `/positiontracker start`  | Start the tracker                    |
+| `/positiontracker stop`   | Stop the tracker                     |
+

pom.xml

@@ -4,7 +4,7 @@
 	<modelVersion>4.0.0</modelVersion>
 	<groupId>edu.whimc</groupId>
 	<artifactId>WHIMC-PositionTracker</artifactId>
-	<version>2.0.5</version>
+	<version>2.1.0</version>
 	<name>WHIMC Position Tracker</name>
 	<description>Track player positions to a database</description>
 

src/main/java/edu/whimc/positiontracker/JoinLeaveListener.java

@@ -6,20 +6,38 @@
 import org.bukkit.event.player.PlayerJoinEvent;
 import org.bukkit.event.player.PlayerQuitEvent;
 
+/**
+ * Handles toggling of data collection based on number of current online players.
+ */
 public class JoinLeaveListener implements Listener {
-
+	/** The instance of the plugin. */
 	private Tracker plugin;
-
+
+	/**
+	 * Constructs a JoinLeaveListener.
+	 *
+	 * @param plugin
+	 */
 	public JoinLeaveListener(Tracker plugin) {
 		this.plugin = plugin;
 	}
-
+
+	/**
+	 * Starts data collection if it's not running already.
+	 *
+	 * @param event the event called when a player joins the server.
+	 */
 	@EventHandler
 	public void onJoin(PlayerJoinEvent event) {
 		if (plugin.isRunning()) return;
 		plugin.startRunner();
 	}
-
+
+	/**
+	 * Stops data collection when there are no players online.
+	 *
+	 * @param event the event called when a player joins the server.
+	 */
 	@EventHandler
 	public void onLeave(PlayerQuitEvent event) {
 		if (Bukkit.getOnlinePlayers().size() != 0) return;

src/main/java/edu/whimc/positiontracker/Tracker.java

@@ -5,12 +5,20 @@
 
 import edu.whimc.positiontracker.sql.Queryer;
 
+/**
+ * The main plugin class.
+ */
 public class Tracker extends JavaPlugin {
-
+	/** The current Task's ID. */
 	private int taskID = -1;
+	/** The debug mode status. */
 	private boolean debug = false;
+	/** The Queryer for the SQL database */
 	private Queryer queryer;
-
+
+	/**
+	 * {@inheritDoc}
+	 */
 	@Override
 	public void onEnable() {
 		saveDefaultConfig();
@@ -34,7 +42,13 @@ public void onEnable() {
 
 	}
 
+	/**
+	 * Starts player location data collection.
+	 *
+	 * @return whether or not the data collection has been successfully started.
+	 */
 	public boolean startRunner() {
+		// check if already running
 		if (taskID != -1) {
 			this.getLogger().warning("The runner has already been started!");
 			return false;
@@ -50,7 +64,13 @@ public boolean startRunner() {
 		return true;
 	}
 
+	/**
+	 * Stops player data collection.
+	 *
+	 * @return whether or not the data collection has been successfully stopped.
+	 */
 	public boolean stopRunner() {
+		// check if already stopped
 		if (!isRunning()) {
 			return false;
 		}
@@ -60,23 +80,41 @@ public boolean stopRunner() {
 		return true;
 	}
 
+	/**
+	 * @return if the data collection is running.
+	 */
 	public boolean isRunning() {
 		return Bukkit.getScheduler().isQueued(taskID);
 	}
 
+	/**
+	 * @return the current task ID.
+	 */
 	public int getTaskID() {
 		return taskID;
 	}
 
+	/**
+	 * Prints the passed String into the server logs.
+	 *
+	 * @param str the String to print.
+	 */
 	public void debugLog(String str) {
+		// check if in debug mode
 		if (!this.debug) return;
 		this.getLogger().info(str);
 	}
 
+	/**
+	 * @return whether or not debug mode is enabled.
+	 */
 	public boolean getDebug() {
 		return this.debug;
 	}
 
+	/**
+	 * @param bool the debug desired status (true = on, false = off).
+	 */
 	public void setDebug(boolean bool) {
 		this.debug = bool;
 	}

src/main/java/edu/whimc/positiontracker/TrackerCommand.java

@@ -5,27 +5,41 @@
 import org.bukkit.command.CommandExecutor;
 import org.bukkit.command.CommandSender;
 
+/**
+ * Main handler for the /positiontracker root command.
+ */
 public class TrackerCommand implements CommandExecutor{
-
+	/** The instance of the plugin. */
 	private Tracker plugin;
-
+
+	/**
+	 * Constructs a TrackerCommand.
+	 *
+	 * @param plugin the instance of the plugin.
+	 */
 	public TrackerCommand(Tracker plugin) {
 		this.plugin = plugin;
 	}
-
+
+	/**
+	 * {@inheritDoc}
+	 */
 	public boolean onCommand(CommandSender sender, Command cmd, String label, String[] args) {
+		// ensure sender is an operator
 		if (!sender.isOp()) {
 			sender.sendMessage(ChatColor.RED + "You must be OP to use this command!");
 			return true;
 		}
-
+
+		// send valid command list if no arguments provided
 		if (args.length == 0) {
 			sendCommands(sender);
 			return true;
 		}
 
 		String arg = args[0];
-
+
+		// toggling debug mode
 		if (arg.equalsIgnoreCase("debug")) {
 			String message = ChatColor.YELLOW + "Console debug messages are now ";
 			if (plugin.getDebug()) {
@@ -41,7 +55,8 @@ public boolean onCommand(CommandSender sender, Command cmd, String label, String
 		}
 
 		boolean running = plugin.isRunning();
-
+
+		// checking plugin status
 		if (arg.equalsIgnoreCase("status")) {
 			String message = ChatColor.YELLOW + "PositionTracker is currently ";
 
@@ -56,8 +71,10 @@ public boolean onCommand(CommandSender sender, Command cmd, String label, String
 			sender.sendMessage(message);
 			return true;
 		}
-
+
+		// starting the tracker
 		if (arg.equalsIgnoreCase("start")) {
+			// notify sender if already running
 			if (running) {
 				sender.sendMessage(ChatColor.RED + "The tracker is already running!");
 				return true;
@@ -72,8 +89,10 @@ public boolean onCommand(CommandSender sender, Command cmd, String label, String
 
 			return true;
 		}
-
+
+		// stopping the tracker
 		if (arg.equalsIgnoreCase("stop")) {
+			// notify sender if already stopped
 			if (!running) {
 				sender.sendMessage(ChatColor.RED + "The tracker is already stopped!");
 				return true;
@@ -88,11 +107,16 @@ public boolean onCommand(CommandSender sender, Command cmd, String label, String
 
 			return true;
 		}
-		
+
 		sendCommands(sender);
 		return true;
 	}
-
+
+	/**
+	 * Sends the list of commands and their usage to the sender.
+	 *
+	 * @param sender the command's sender.
+	 */
 	private void sendCommands(CommandSender sender) {
 		sender.sendMessage(ChatColor.DARK_RED + "" + ChatColor.BOLD + "Position Tracker");
 		sender.sendMessage(ChatColor.RED + "" + ChatColor.ITALIC +