Core javadoc/general tidying (Issue 633)

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

src/com/dmdirc/Channel.java

@@ -381,11 +381,21 @@ public final class Channel extends MessageTarget
         }
     }
     
+    /**
+     * Adds a ChannelClient to this Channel.
+     * 
+     * @param client The client to be added
+     */
     public void addClient(final ChannelClientInfo client) {
         window.addName(client);
         tabCompleter.addEntry(client.getNickname());   
     }
     
+    /**
+     * Removes the specified ChannelClient from this channel.
+     * 
+     * @param client The client to be removed
+     */
     public void removeClient(final ChannelClientInfo client) {
         window.removeName(client);
         tabCompleter.removeEntry(client.getNickname());
@@ -395,12 +405,22 @@ public final class Channel extends MessageTarget
         }
     }
     
+    /**
+     * Renames a client that is in this channel.
+     * 
+     * @param oldName The old nickname of the client
+     * @param newName The new nickname of the client
+     */
     public void renameClient(final String oldName, final String newName) {
         tabCompleter.removeEntry(oldName);
         tabCompleter.addEntry(newName);        
         refreshClients();
     }
     
+    /**
+     * Refreshes the list of clients stored by this channel. Should be called
+     * when (visible) user modes or nicknames change.
+     */
     public void refreshClients() {
         window.updateNames();
     }

src/com/dmdirc/ChannelEventHandler.java

@@ -42,8 +42,14 @@ public final class ChannelEventHandler extends EventHandler implements
         IChannelNickChanged, IChannelModeChanged, IChannelUserModeChanged,
         IChannelCTCP, IAwayStateOther {
     
+    /** The channel that owns this event handler. */
     private final Channel owner;
     
+    /**
+     * Creates a new instance of ChannelEventHandler.
+     * 
+     * @param owner The channel that owns this event handler.
+     */
     public ChannelEventHandler(final Channel owner) {
         this.owner = owner;
     }
@@ -65,6 +71,12 @@ public final class ChannelEventHandler extends EventHandler implements
         return owner.getServer().getParser();
     }
     
+    /**
+     * Determines if the specified client represents us.
+     * 
+     * @param client The client to be tested
+     * @return True if the client is ourself, false otherwise.
+     */
     protected boolean isMyself(final ChannelClientInfo client) {
         return client.getClient().equals(owner.getServer().getParser().getMyself());
     }

src/com/dmdirc/FrameContainer.java

@@ -23,7 +23,6 @@
 package com.dmdirc;
 
 import com.dmdirc.config.ConfigManager;
-import com.dmdirc.config.IdentityManager;
 import com.dmdirc.interfaces.IconChangeListener;
 import com.dmdirc.interfaces.NotificationListener;
 import com.dmdirc.interfaces.SelectionListener;

src/com/dmdirc/IconManager.java

@@ -48,7 +48,10 @@ public final class IconManager implements ConfigChangeListener {
     /** Previously created IconManager instance. */
     private static final IconManager me = new IconManager();
         
+    /** A map of existing icons. */
     private final Map<String, Icon> icons;
+    
+    /** A map of existing images. */
     private final Map<String, Image> images;
     
     /** Creates a new instance of IconManager. */

src/com/dmdirc/IgnoreList.java

@@ -23,6 +23,7 @@
 package com.dmdirc;
 
 import com.dmdirc.parser.RegexStringList;
+
 import java.util.ArrayList;
 import java.util.List;
 

src/com/dmdirc/Query.java

@@ -42,8 +42,8 @@ import com.dmdirc.ui.WindowManager;
 import com.dmdirc.ui.input.TabCompleter;
 import com.dmdirc.ui.interfaces.InputWindow;
 import com.dmdirc.ui.interfaces.QueryWindow;
-import java.awt.Toolkit;
 
+import java.awt.Toolkit;
 import java.io.Serializable;
 
 /**

src/com/dmdirc/Raw.java

@@ -55,8 +55,6 @@ public final class Raw extends WritableFrameContainer implements IDataIn,
     /** An InputWindow used for displaying the raw data.*/
     private InputWindow window;
     
-    private boolean isClosing = false;
-    
     /**
      * Creates a new instance of Raw.
      *

src/com/dmdirc/Server.java

@@ -1178,6 +1178,9 @@ public final class Server extends WritableFrameContainer implements Serializable
         checkModeAliases();
     }
     
+    /**
+     * Checks that we have the neccessary mode aliases for this server.
+     */
     private void checkModeAliases() {
         // Check we have mode aliases
         final String modes = parser.getBoolChanModes() + parser.getListChanModes()

src/com/dmdirc/WritableFrameContainer.java

@@ -143,7 +143,7 @@ public abstract class WritableFrameContainer extends FrameContainer {
     }
     
     /**
-     * Handles general server notifications (i.e., ones note tied to a
+     * Handles general server notifications (i.e., ones not tied to a
      * specific window). The user can select where the notifications should
      * go in their config.
      *
@@ -155,6 +155,13 @@ public abstract class WritableFrameContainer extends FrameContainer {
                 getConfigManager().getOption("notifications", messageType, "self"), args);
     }
     
+    /**
+     * Despatches a notification of the specified type to the specified target.
+     * 
+     * @param messageType The type of the message that is being sent
+     * @param messageTarget The target of the message
+     * @param args The arguments for the message
+     */
     protected void despatchNotification(final String messageType,
             final String messageTarget, final Object... args) {
         

src/com/dmdirc/actions/Action.java

@@ -55,10 +55,15 @@ public class Action extends ActionModel implements Serializable {
      */
     private static final long serialVersionUID = 1;
 
+    /** The domain name for condition trees. */
     private static final String DOMAIN_CONDITIONTREE = "conditiontree".intern();
+    /** The domain name for format changes. */
     private static final String DOMAIN_FORMAT = "format".intern();
+    /** The domain name for meta-data. */
     private static final String DOMAIN_METADATA = "metadata".intern();
+    /** The domain name for response information. */
     private static final String DOMAIN_RESPONSE = "response".intern();
+    /** The domain name for triggers. */
     private static final String DOMAIN_TRIGGERS = "triggers".intern();
 
     /** The file containing this action. */
@@ -277,6 +282,12 @@ public class Action extends ActionModel implements Serializable {
         }
     }
 
+    /**
+     * Loads a list of triggers with the specified names.
+     * 
+     * @param newTriggers A list of trigger names
+     * @return True if all triggers are valid and compatible, false otherwise.
+     */
     private boolean loadTriggers(final List<String> newTriggers) {
         triggers = new ActionType[newTriggers.size()];
 
@@ -449,6 +460,12 @@ public class Action extends ActionModel implements Serializable {
         }
     }
 
+    /**
+     * Reads a condition from the specified configuration section.
+     * 
+     * @param data The relevant section of the action configuration
+     * @return True if the condition is valid, false otherwise
+     */
     private boolean readCondition(final Map<String,String> data) {
         int arg = 0;
         ActionComponent component = null;
@@ -518,6 +535,14 @@ public class Action extends ActionModel implements Serializable {
         return true;
     }
 
+    /**
+     * Reads a component from the specified data section for the specified argument.
+     * 
+     * @param data The relevant section of the action configuration
+     * @param arg The argument number that the component should apply to
+     * @return The corresponding ActionComponent, or null if the specified
+     * component is invalid.
+     */
     private ActionComponent readComponent(final Map<String, String> data, final int arg) {
         final String componentName = data.get("component");
         ActionComponent component;

src/com/dmdirc/actions/ActionCondition.java

@@ -47,7 +47,9 @@ public class ActionCondition {
     private String starget;
     
     /**
-     * Creates a new instance of ActionCondition.
+     * Creates a new instance of ActionCondition that compares the output of
+     * a component to a string.
+     * 
      * @param arg The argument number to be tested
      * @param component The component to be tested
      * @param comparison The comparison to be used
@@ -63,6 +65,13 @@ public class ActionCondition {
         this.target = target;
     }
     
+    /**
+     * Creates a new instance of ActionCondition that compares two strings.
+     * 
+     * @param starget The first target for comparison.
+     * @param comparison The comparison to be used
+     * @param target The second target for the comparison
+     */
     public ActionCondition(final String starget, final ActionComparison comparison,
             final String target) {
         super();
@@ -162,10 +171,20 @@ public class ActionCondition {
         this.target = target;
     }
 
+    /**
+     * Retrieves the starget of this condition.
+     * 
+     * @return This condition's starget, or null if none was set.
+     */
     public String getStarget() {
         return starget;
     }
 
+    /**
+     * Sets the starget for this condition.
+     * 
+     * @param starget The new starget for this condition.
+     */
     public void setStarget(final String starget) {
         this.starget = starget;
     }

src/com/dmdirc/actions/ActionGroup.java

@@ -39,58 +39,120 @@ public class ActionGroup extends ArrayList<Action> {
      */
     private static final long serialVersionUID = 1;    
     
+    /** The name of this action group. */
     private String name = null;
     
+    /** The description of this action group. */
     private String description = null;
     
+    /** The author of this action group. */
     private String author = null;
     
+    /** The component number of this action group (for updating). */
     private int component = -1;
     
+    /** The version number of this action group. */
     private int version = -1;
     
+    /** A list of settings used by this action group. */
     private final List<ActionSetting> settings = new ArrayList<ActionSetting>();
 
+    /**
+     * Creates a new instance of ActionGroup.
+     * 
+     * @param name The name of this action group
+     */
     public ActionGroup(final String name) {
         this.name = name;
     }
 
+    /**
+     * Retrieves the author of this ActionGroup.
+     * 
+     * @return This action group's author, or null if the author isn't specified
+     */
     public String getAuthor() {
         return author;
     }
 
+    /**
+     * Sets the author of this ActionGroup.
+     * 
+     * @param author The new author for this action group
+     */
     public void setAuthor(final String author) {
         this.author = author;
     }
 
+    /**
+     * Retrieves the description of this action group.
+     * 
+     * @return This action group's description, or null if none is specified
+     */
     public String getDescription() {
         return description;
     }
 
+    /**
+     * Sets the description for this action group.
+     * 
+     * @param description The new description for this action group
+     */
     public void setDescription(final String description) {
         this.description = description;
     }
 
+    /**
+     * Retrieves the name of this action group.
+     * 
+     * @return This action group's name
+     */
     public String getName() {
         return name;
     }
 
+    /**
+     * Retrieves a list of settings used by this action group.
+     * 
+     * @return A list of settings used by this action group.
+     */
     public List<ActionSetting> getSettings() {
         return settings;
     }
 
+    /**
+     * Retrieves the version number of this action group.
+     * 
+     * @return This action group's version number, or -1 if none is specified.
+     */
     public int getVersion() {
         return version;
     }
 
+    /**
+     * Sets the version of this action group.
+     * 
+     * @param version This action group's new version number.
+     */
     public void setVersion(final int version) {
         this.version = version;
     }
 
+    /**
+     * Retrieves the addon site component number for this action group.
+     * 
+     * @return The component number for this action group, or -1 if none is
+     * specified.
+     */
     public int getComponent() {
         return component;
     }
 
+    /**
+     * Sets the addon site component number for this action group.
+     * 
+     * @param component The component number for this action group
+     */
     public void setComponent(final int component) {
         this.component = component;
     }

src/com/dmdirc/actions/ActionSetting.java

@@ -23,18 +23,33 @@
 package com.dmdirc.actions;
 
 /**
- *
+ * Represents a setting required by an Action pack.
+ * 
  * @author chris
  */
 public class ActionSetting {
     
+    /** The possible types of setting used by action packs. */
     public static enum TYPE {
+        /** A freeform text setting. */
         TEXT,
+        /** A colour setting. */
         COLOUR,
+        /** A numerical setting. */
         NUMBER,
+        /** A boolean setting. */
         BOOLEAN
     }
 
+    /**
+     * Creates a new instance of ActionSetting.
+     * 
+     * @param type The type of setting.
+     * @param setting The name of the setting.
+     * @param title The user-friendly name of the setting.
+     * @param tooltip The tooltip to show for this setting.
+     * @param fallback The default value of this setting.
+     */
     public ActionSetting(TYPE type, String setting, String title, String tooltip, String fallback) {
         this.type = type;
         this.setting = setting;
@@ -43,32 +58,62 @@ public class ActionSetting {
         this.fallback = fallback;
     }
     
+    /** The type of this setting. */
     private TYPE type;
     
+    /** The name (key) of this setting. */
     private String setting;
     
+    /** The user-friendly name of this setting. */
     private String title;
     
+    /** The tooltip to show for this setting. */
     private String tooltip;
     
+    /** The default value of this setting. */
     private String fallback;
 
+    /**
+     * Retrieves the default value of this setting.
+     * 
+     * @return This setting's default value.
+     */
     public String getFallback() {
         return fallback;
     }
 
+    /**
+     * Retrieves the name (key) of this setting.
+     * 
+     * @return This setting's name
+     */    
     public String getSetting() {
         return setting;
     }
 
+    /**
+     * Retrieves the user-friendly name of this setting.
+     * 
+     * @return This setting's user-friendly name.
+     */    
     public String getTitle() {
         return title;
     }
 
+    /**
+     * Retrieves the tooltip text of this setting.
+     * 
+     * @return This setting's tooltip text.
+     */    
     public String getTooltip() {
         return tooltip;
     }
 
+    /**
+     * Retrieves the type of this setting.
+     * 
+     * @return This setting's type.
+     */    
     public TYPE getType() {
         return type;
     }

src/com/dmdirc/actions/ConditionTree.java

@@ -33,18 +33,39 @@ import java.util.Deque;
  */
 public class ConditionTree {
 
+    /** The possible operations on a condition tree. */
     public static enum OPERATION {
-        AND, OR, VAR, NOT, NOOP
+        /** Only passes if both subtrees are true. */
+        AND,
+        /** Passes if either of the subtrees are true. */
+        OR,
+        /** Passes if the specified argument is true. */
+        VAR,
+        /** Only passes iof the left subtree fails to pass. */
+        NOT,
+        /** Doesn't do anything (an empty tree). */
+        NOOP
     }
        
+    /** The left subtree of this tree. */
     private ConditionTree leftArg = null;
 
+    /** The right subtree of this tree. */
     private ConditionTree rightArg = null;
 
+    /** The argument of this tree (only used for VAR ops). */
     private int argument = -1;
 
+    /** The operation that this tree performs. */
     private OPERATION op;
     
+    /**
+     * Creates a new ConditionTree for a binary operation.
+     * 
+     * @param op The binary operation to perform
+     * @param leftArg The left argument/subtree
+     * @param rightArg The right argument/subtree
+     */
     private ConditionTree(final OPERATION op, final ConditionTree leftArg,
             final ConditionTree rightArg) {
         assert(op != OPERATION.VAR);
@@ -57,6 +78,12 @@ public class ConditionTree {
         this.rightArg = rightArg;
     }
     
+    /**
+     * Creates a new ConditionTree for a unary operation.
+     * 
+     * @param op
+     * @param argument
+     */
     private ConditionTree(final OPERATION op, final ConditionTree argument) {
         assert(op == OPERATION.NOT);
         
@@ -64,11 +91,20 @@ public class ConditionTree {
         this.leftArg = argument;
     }    
     
+    /**
+     * Creates a new ConditionTree for a VAR operation with the specified
+     * argument number.
+     * 
+     * @param argument The number of the argument that's to be tested.
+     */
     private ConditionTree(final int argument) {
         this.op = OPERATION.VAR;
         this.argument = argument;
     }
     
+    /**
+     * Creates a new ConditionTree for a NOOP operation.
+     */
     private ConditionTree() {
         this.op = OPERATION.NOOP;
     }
@@ -143,7 +179,7 @@ public class ConditionTree {
      * Parses the specified string into a condition tree.
      * 
      * @param string The string to be parsed
-     * @return The corresponding condition tree, or null if there as an error
+     * @return The corresponding condition tree, or null if there was an error
      * while parsing the data
      */
     public static ConditionTree parseString(final String string) {
@@ -169,6 +205,14 @@ public class ConditionTree {
         return parseStack(stack);
     }
     
+    /**
+     * Parses the specified stack of elements, and returns a corresponding
+     * ConditionTree.
+     * 
+     * @param stack The stack to be read.
+     * @return The corresponding condition tree, or null if there was an error
+     * while parsing the data.
+     */
     @SuppressWarnings("fallthrough")
     private static ConditionTree parseStack(final Deque<Object> stack) {
         final Deque<Object> myStack = new ArrayDeque<Object>();
@@ -236,6 +280,13 @@ public class ConditionTree {
         return new ConditionTree();
     }
     
+    /**
+     * Reads and returns a single term from the specified stack.
+     * 
+     * @param stack The stack to be read
+     * @return The ConditionTree representing the last element on the stack,
+     * or null if it was not possible to create one.
+     */
     private static ConditionTree readTerm(final Deque<Object> stack) {
         final Object first = stack.pollFirst();
         
@@ -254,6 +305,14 @@ public class ConditionTree {
         }
     }
     
+    /**
+     * Pops elements off of the end of the specified stack until an opening
+     * bracket is reached, and then returns the parsed content of the bracket.
+     * 
+     * @param stack The stack to be read for the bracket
+     * @return The parsed contents of the bracket, or null if the brackets were
+     * mismatched.
+     */
     private static ConditionTree readBracket(final Deque<Object> stack) {
         final Deque<Object> tempStack = new ArrayDeque<Object>();
         boolean found = false;
@@ -275,6 +334,12 @@ public class ConditionTree {
         }
     }
     
+    /**
+     * Determines if the specified character represents a single digit.
+     * 
+     * @param target The character to be tested
+     * @return True if the character is a digit, false otherwise
+     */
     private static boolean isInt(final char target) {
         return target >= '0' && target <= '9';
     }

src/com/dmdirc/actions/metatypes/ChannelEvents.java

@@ -44,7 +44,9 @@ public enum ChannelEvents implements ActionMetaType {
     /** Channel event with source and victim. */
     CHANNEL_SOURCED_EVENT_WITH_VICTIM(new String[]{"channel", "user", "victim", "message"}, Channel.class, ChannelClientInfo.class, ChannelClientInfo.class, String.class);
     
+    /** The names of the arguments for this meta type. */
     private String[] argNames;
+    /** The classes of the arguments for this meta type. */
     private Class[] argTypes;
     
     /**

src/com/dmdirc/actions/metatypes/ClientEvents.java

@@ -47,7 +47,9 @@ public enum ClientEvents implements ActionMetaType {
     /** Unknown command event type. */
     UNKNOWN_COMMAND(new String[]{"source", "command", "arguments"}, FrameContainer.class, String.class, String[].class);
     
+    /** The names of the arguments for this meta type. */
     private String[] argNames;
+    /** The classes of the arguments for this meta type. */
     private Class[] argTypes;
     
     /**

src/com/dmdirc/actions/metatypes/PluginEvents.java

@@ -35,7 +35,9 @@ public enum PluginEvents implements ActionMetaType {
     /** Plugin event type. */
     PLUGIN_EVENT(new String[]{"plugin"}, PluginInfo.class);
     
+    /** The names of the arguments for this meta type. */
     private String[] argNames;
+    /** The classes of the arguments for this meta type. */
     private Class[] argTypes;
     
     /**

src/com/dmdirc/actions/metatypes/QueryEvents.java

@@ -37,7 +37,9 @@ public enum QueryEvents implements ActionMetaType {
     /** Query event with argument. */
     QUERY_EVENT_WITH_ARG(new String[]{"query", "message"}, Query.class, String.class);
     
+    /** The names of the arguments for this meta type. */
     private String[] argNames;
+    /** The classes of the arguments for this meta type. */
     private Class[] argTypes;
     
     /**

src/com/dmdirc/actions/metatypes/ServerEvents.java

@@ -52,7 +52,9 @@ public enum ServerEvents implements ActionMetaType {
     /** Server event type. */
     SERVER_EVENT(new String[]{"server"}, Server.class);
     
+    /** The names of the arguments for this meta type. */
     private String[] argNames;
+    /** The classes of the arguments for this meta type. */
     private Class[] argTypes;
     
     /**

src/com/dmdirc/actions/wrappers/ActionWrapper.java

@@ -23,6 +23,7 @@
 package com.dmdirc.actions.wrappers;
 
 import com.dmdirc.actions.Action;
+
 import java.util.ArrayList;
 import java.util.List;
 

src/com/dmdirc/actions/wrappers/PerformWrapper.java

@@ -42,6 +42,7 @@ import java.util.List;
  */
 public class PerformWrapper extends ActionWrapper {
     
+    /** A singleton instance of the Perform Wrapper. */
     private static PerformWrapper me = new PerformWrapper();
     
     /**