Fully javadoc'd the command parser package

git-svn-id: http://svn.dmdirc.com/trunk@145 00569f92-eb28-0410-84fd-f71c24880f

src/uk/org/ownage/dmdirc/commandparser/ChannelCommand.java

@@ -26,7 +26,7 @@ import uk.org.ownage.dmdirc.Channel;
 import uk.org.ownage.dmdirc.Server;
 
 /**
- *
+ * Represents a command which can be performed only in the context of a channel
  * @author chris
  */
 public abstract class ChannelCommand extends Command {
@@ -36,5 +36,11 @@ public abstract class ChannelCommand extends Command {
         super();
     }
     
+    /**
+     * Executes this command
+     * @param server The server instance that this command is being executed on
+     * @param channel The channel instance that this command is being executed on
+     * @param args Arguments passed to this command
+     */    
     public abstract void execute(Server server, Channel channel, String... args);    
 }

src/uk/org/ownage/dmdirc/commandparser/ChannelCommandParser.java

@@ -26,34 +26,63 @@ import uk.org.ownage.dmdirc.Channel;
 import uk.org.ownage.dmdirc.Server;
 
 /**
- *
+ * A command parser that is tailored for use in a channel environment. Handles
+ * both channel and server commands.
  * @author chris
  */
 public class ChannelCommandParser extends CommandParser {
     
+    /**
+     * The server instance that this parser is attached to
+     */
     private Server server;
+    /**
+     * The channel instance that this parser is attached to
+     */
     private Channel channel;
     
-    /** Creates a new instance of ChannelCommandParser */
+    /**
+     * Creates a new instance of ChannelCommandParser
+     * @param server The server instance that this parser is attached to
+     * @param channel The channel instance that this parser is attached to
+     */
     public ChannelCommandParser(Server server, Channel channel) {
         super();
         
         this.server = server;
         this.channel = channel;
     }
-
+    
+    /** Loads the relevant commands into the parser */
     protected void loadCommands() {
         throw new UnsupportedOperationException("Not implemented yet");
     }
-
+    
+    /**
+     * Executes the specified command with the given arguments.
+     * @param command The command to be executed
+     * @param args The arguments to the command
+     */    
     protected void executeCommand(Command command, String... args) {
         throw new UnsupportedOperationException("Not implemented yet");
     }
-
+    
+    /**
+     * Called when the user attempted to issue a command (i.e., used the command
+     * character) that wasn't found. It could be that the command has a different
+     * arity, or that it plain doesn't exist.
+     * @param command The command the user tried to execute
+     * @param args The arguments passed to the command
+     */    
     protected void handleInvalidCommand(String command, String... args) {
         throw new UnsupportedOperationException("Not implemented yet");
     }
-
+    
+    /**
+     * Called when the input was a line of text that was not a command. This normally
+     * means it is sent to the server/channel/user as-is, with no further processing.
+     * @param line The line input by the user
+     */    
     protected void handleNonCommand(String line) {
         throw new UnsupportedOperationException("Not implemented yet");
     }

src/uk/org/ownage/dmdirc/commandparser/Command.java

@@ -25,21 +25,48 @@ package uk.org.ownage.dmdirc.commandparser;
 import uk.org.ownage.dmdirc.Server;
 
 /**
- *
+ * Represents a generic command
  * @author chris
  */
 public abstract class Command {
     
+    /**
+     * The name of this command (i.e., the string used by the user to execute it)
+     */
     protected String name;
+    /**
+     * The arity of this command
+     */
     protected int arity = 0;
+    /**
+     * Whether this command is polyadic or not
+     */
     protected boolean polyadic;
+    /**
+     * Whether this command should be shown in help output
+     */
     protected boolean show = true;
+    /**
+     * A textual description of this command's arguments
+     */
     protected String arguments = "<unknown>";
+    /**
+     * A description of this command
+     */
     protected String description = "unknown";
     
+    /**
+     * Creates a new instance of Command
+     */
     public Command() {
     }
     
+    /**
+     * Returns the signature of this command. For polyadic commands, the signature
+     * is simply the name. For other commands, the signature is a concatenation of
+     * the name, a literal "/", and the arity.
+     * @return The signature of this command
+     */
     public String getSignature() {
         if (polyadic) {
             return name;
@@ -48,10 +75,18 @@ public abstract class Command {
         }
     }
     
+    /**
+     * Returns whether or not this command should be shown in help messages
+     * @return True iff the command should be shown, false otherwise
+     */
     public boolean showInHelp() {
         return show;
     }
     
+    /**
+     * Returns a string representing the help message for this command
+     * @return the help message for this command
+     */
     public String getHelp() {
         return name+" "+arguments+" - "+description;
     }

src/uk/org/ownage/dmdirc/commandparser/CommandManager.java

@@ -26,17 +26,29 @@ import java.util.Vector;
 import uk.org.ownage.dmdirc.commandparser.commands.*;
 
 /**
- *
+ * The command manager creates and manages a single instance of all commands,
+ * and provides methods to load each group of commands into a parser instance
  * @author chris
  */
 public class CommandManager {
     
+    /**
+     * The commands that have been instansiated
+     */
     private static Vector<Command> serverCommands;
            
+    /**
+     * Loads all channel commands into the specified parser
+     * @param parser The parser to load commands into
+     */
     public static void loadChannelCommands(CommandParser parser) {
         throw new UnsupportedOperationException("Not implemented yet");        
     }
     
+    /**
+     * Loads all server commands into the specified parser
+     * @param parser The parser to load commands into
+     */
     public static void loadServerCommands(CommandParser parser) {
         if (serverCommands == null) {
             serverCommands = new Vector<Command>(0,1);

src/uk/org/ownage/dmdirc/commandparser/CommandParser.java

@@ -26,11 +26,16 @@ import java.util.Hashtable;
 import uk.org.ownage.dmdirc.Config;
 
 /**
- *
+ * Represents a generic command parser. A command parser takes a line of input
+ * from the user, determines if it is an attempt at executing a command (based
+ * on the character at the start of the string), and handles it appropriately.
  * @author chris
  */
 abstract public class CommandParser {
     
+    /**
+     * Commands that are associated with this parser
+     */
     private Hashtable<String,Command> commands;
     
     /** Creates a new instance of CommandParser */
@@ -42,11 +47,18 @@ abstract public class CommandParser {
     /** Loads the relevant commands into the parser */
     protected abstract void loadCommands();
     
+    /**
+     * Registers the specified command with this parser
+     * @param command Command to be registered
+     */
     public void registerCommand(Command command) {
         commands.put(command.getSignature(), command);
     }
     
-    /** Parses the specified string as a command */
+    /**
+     * Parses the specified string as a command
+     * @param line The line to be parsed
+     */
     public void parseCommand(String line) {
         if (line.charAt(0) == Config.getOption("general","commandchar").charAt(0)) {
             String[] args = line.split(" ");
@@ -72,9 +84,26 @@ abstract public class CommandParser {
         }
     }
     
+    /**
+     * Executes the specified command with the given arguments.
+     * @param command The command to be executed
+     * @param args The arguments to the command
+     */
     abstract protected void executeCommand(Command command, String... args);
     
+    /**
+     * Called when the user attempted to issue a command (i.e., used the command
+     * character) that wasn't found. It could be that the command has a different
+     * arity, or that it plain doesn't exist.
+     * @param command The command the user tried to execute
+     * @param args The arguments passed to the command
+     */
     abstract protected void handleInvalidCommand(String command, String... args);
 
+    /**
+     * Called when the input was a line of text that was not a command. This normally
+     * means it is sent to the server/channel/user as-is, with no further processing.
+     * @param line The line input by the user
+     */
     abstract protected void handleNonCommand(String line);
 }

src/uk/org/ownage/dmdirc/commandparser/ServerCommand.java

@@ -26,7 +26,8 @@ import uk.org.ownage.dmdirc.Channel;
 import uk.org.ownage.dmdirc.Server;
 
 /**
- *
+ * Represents a generic server command. Server commands are associated with 
+ * a server instance.
  * @author chris
  */
 public abstract class ServerCommand extends Command {
@@ -36,5 +37,10 @@ public abstract class ServerCommand extends Command {
         super();
     }
     
+    /**
+     * Executes this command
+     * @param server The server instance that this command is being executed on
+     * @param args Arguments passed to this command
+     */    
     public abstract void execute(Server server, String... args);
 }

src/uk/org/ownage/dmdirc/commandparser/ServerCommandParser.java

@@ -25,32 +25,56 @@ package uk.org.ownage.dmdirc.commandparser;
 import uk.org.ownage.dmdirc.Server;
 
 /**
- *
+ * A command parser used in the context of a server
  * @author chris
  */
 public class ServerCommandParser extends CommandParser {
     
+    /**
+     * The server instance that this parser is attached to
+     */
     private Server server;
     
-    /** Creates a new instance of ServerCommandParser */
+    /**
+     * Creates a new instance of ServerCommandParser
+     * @param server The server instance that this parser is attached to
+     */
     public ServerCommandParser(Server server) {
         super();
         
         this.server = server;
     }
-
+    
+    /** Loads the relevant commands into the parser */
     protected void loadCommands() {
         CommandManager.loadServerCommands(this);
     }
-
+    
+    /**
+     * Executes the specified command with the given arguments.
+     * @param command The command to be executed
+     * @param args The arguments to the command
+     */
     protected void executeCommand(Command command, String... args) {
         ((ServerCommand)command).execute(server, args);
     }
-
+    
+    /**
+     * Called when the user attempted to issue a command (i.e., used the command
+     * character) that wasn't found. It could be that the command has a different
+     * arity, or that it plain doesn't exist.
+     * @param command The command the user tried to execute
+     * @param args The arguments passed to the command
+     */
     protected void handleInvalidCommand(String command, String... args) {
         server.addLine("Unknown command: "+command+"/"+(args.length-1));
     }
-
+    
+    /**
+     * Called when the input was a line of text that was not a command. This normally
+     * means it is sent to the server/channel/user as-is, with no further processing.
+     * @param line The line input by the user
+     */
     protected void handleNonCommand(String line) {
         server.getParser().sendLine(line);
     }

src/uk/org/ownage/dmdirc/commandparser/commands/Test.java

@@ -27,7 +27,8 @@ import uk.org.ownage.dmdirc.commandparser.Command;
 import uk.org.ownage.dmdirc.commandparser.ServerCommand;
 
 /**
- *
+ * A sample command. Takes no arguments, and merely prints the SVN ID string of 
+ * the IRC parser.
  * @author chris
  */
 public class Test extends ServerCommand {
@@ -42,6 +43,11 @@ public class Test extends ServerCommand {
         show = true;
     }
 
+    /**
+     * Executes this command
+     * @param server The server instance that this command is being executed on
+     * @param args Arguments passed to this command
+     */
     public void execute(Server server, String... args) {
         server.addLine(server.getParser().getSvnInfo());
     }