documented command processor

Author: webpigeon

src/main/java/uk/co/unitycoders/pircbotx/commandprocessor/Command.java

@@ -23,9 +23,33 @@
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
+/**
+ * Command annotation.
+ * 
+ * This annotation is used to tag a method as being a command the bot should
+ * recognise and call when certian words or phrases are mentioned in a channel.
+ * 
+ * The method must take exactly 1 argument, of type MessageEvent<PircBotX>, this
+ * will be passed directly from pircbotx and so will have all features which the
+ * framework provides to it.
+ * 
+ * @author webpigeon
+ * 
+ */
 @Retention(RetentionPolicy.RUNTIME)
 @Target({ ElementType.METHOD })
 public @interface Command
 {
+
+	/**
+	 * Command trigger words.
+	 * 
+	 * This is used to tell the bot what keywords it should respond to when
+	 * processing actions. The keyword "default" will be called automatically if
+	 * no keyword is specified. If an array of keywords is passed the bot will
+	 * register all keywords for this method.
+	 * 
+	 * @return The keywords for this command
+	 */
 	public String[] value() default "default";
 }

src/main/java/uk/co/unitycoders/pircbotx/commandprocessor/CommandListener.java

@@ -23,7 +23,10 @@
 import org.pircbotx.hooks.events.MessageEvent;
 
 /**
- *
+ * Command Processor wrapper class.
+ * 
+ * This class is notified by pircbotx when the bot gets a message. It's sole
+ * purpose is to act as an adapter between the command processor and pircbotx.
  */
 public class CommandListener extends ListenerAdapter<PircBotX>
 {

src/main/java/uk/co/unitycoders/pircbotx/commandprocessor/CommandProcessor.java

@@ -32,20 +32,47 @@
 /**
  * centrally managed command parsing.
  * 
+ * This class is responsible to breaking IRC messages into commands which the
+ * bot can understand. It contains a list of modules and the methods which are
+ * tagged with the command annotation. Classes must be registered with the
+ * Command Processor in order for the processor to recognise them as commands.
+ * 
  */
 public class CommandProcessor
 {
 	private final Pattern regex;
 	private final Map<String, Object> commands;
 	private final Map<String, Map<String, Method>> callbacks;
 
+	/**
+	 * Create a new command processor.
+	 * 
+	 * This will create a new command processor and will initialise the regex
+	 * pattern the bot will use to match commands. It will also create the maps
+	 * needed to store information about the commands.
+	 * 
+	 * @param trigger the first character of any line directed at the bot
+	 */
 	public CommandProcessor(char trigger)
 	{
 		this.regex = Pattern.compile(trigger + "([a-z0-9]+)(?: ([a-z0-9]+))?(?: (.*))?");
 		this.commands = new HashMap<String, Object>();
 		this.callbacks = new HashMap<String, Map<String, Method>>();
 	}
 
+	/**
+	 * Register a new module and extract it's commands.
+	 * 
+	 * This method will look at target and process any method which has been
+	 * annotated with the command annotation. It will then remember the module
+	 * and command names for use when processing messages.
+	 * 
+	 * The module's name will need to be put before any command. This is to
+	 * prevent two modules conflicting with the same named commands.
+	 * 
+	 * @param name the name of the module
+	 * @param target the module object
+	 */
 	public void register(String name, Object target)
 	{
 		Map<String, Method> methods = new HashMap<String, Method>();
@@ -69,6 +96,16 @@ public void register(String name, Object target)
 		callbacks.put(name, methods);
 	}
 
+	/**
+	 * Process an IRC message to see if the bot needs to respond.
+	 * 
+	 * This method takes an IRC message and splits it into it's component parts.
+	 * if the action is valid it will then call the call method to process the
+	 * event.
+	 * 
+	 * @param event the event to be processed
+	 * @throws Exception
+	 */
 	public void invoke(MessageEvent<PircBotX> event) throws Exception
 	{
 		Matcher matcher = regex.matcher(event.getMessage());
@@ -108,6 +145,15 @@ public void invoke(MessageEvent<PircBotX> event) throws Exception
 		}
 	}
 
+	/**
+	 * Call a module's command with required arguments.
+	 * 
+	 * @param type the name of the module
+	 * @param cmd the name of the command
+	 * @param args the arguments to pass to the method associated with command
+	 * @return true if method was called, false if not
+	 * @throws Exception if the method throws an exception.
+	 */
 	private boolean call(String type, String cmd, Object... args) throws Exception
 	{
 		Object obj = commands.get(type);
@@ -126,13 +172,24 @@ private boolean call(String type, String cmd, Object... args) throws Exception
 		return true;
 	}
 
+	/**
+	 * Get a list of modules registered with the command processor.
+	 * 
+	 * @return the list of module names
+	 */
 	public String[] getModules()
 	{
 		Collection<String> modules = callbacks.keySet();
 		String[] moduleArray = new String[modules.size()];
 		return modules.toArray(moduleArray);
 	}
 
+	/**
+	 * Gets a list of commands which are registered with the command processor
+	 * 
+	 * @param moduleName the name of the module to get the commands from.
+	 * @return the list of command names, or null if command doesn't exist.
+	 */
 	public String[] getCommands(String moduleName)
 	{
 		Map<String, Method> commands = callbacks.get(moduleName);