Core javadoc. Fixes issue 633.

Removed some now-unused popup type stuff

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

src/com/dmdirc/CustomWindow.java

 import com.dmdirc.ui.interfaces.Window;
 
 /**
+ * A generic custom window implementation.
  * 
  * @author chris
  */
     /** This custom window's title. */
     private final String title;
 
+    /** The window used by this container. */
     private Window window;
 
+    /** This window's parent window. */
     private Window parent = null;
 
+    /**
+     * Creates a new custom window as a child of the specified window.
+     * 
+     * @param name The name of this custom window
+     * @param title The title of this custom window
+     * @param parent The parent of this custom window
+     */
     public CustomWindow(final String name, final String title,
             final Window parent) {
         super();
         window.setVisible(true);
     }
 
+    /**
+     * Creates a new custom window as a top-level window.
+     * 
+     * @param name The name of this custom window
+     * @param title The parent of this custom window
+     */
     public CustomWindow(final String name, final String title) {
         super();
 
         return title;
     }
 
+    /** {@inheritDoc} */
     @Override
     public ConfigManager getConfigManager() {
         return parent == null ? IdentityManager.getGlobalConfig() : parent

src/com/dmdirc/commandline/RemoteInterface.java

 import java.util.List;
 
 /**
- *
+ * Defines the interface that is available using RMI.
+ * 
  * @author chris
  */
 public interface RemoteInterface extends Remote {
     
+    /**
+     * Connects to the specified list of addresses.
+     * 
+     * @param addresses The addresses to connect to.
+     * @throws java.rmi.RemoteException on problems communicating
+     */
     void connect(List<IrcAddress> addresses) throws RemoteException;
 
 }

src/com/dmdirc/commandline/RemoteServer.java

 import java.util.List;
 
 /**
- *
+ * An RMI server that allows other clients to interact with DMDirc.
+ * 
  * @author chris
  */
 public class RemoteServer implements RemoteInterface {
     
+    /**
+     * Creates a new instance of RemoteServer.
+     */
     public RemoteServer() {
         super();
     }
     
+    /** {@inheritDoc} */
     @Override
     public void connect(List<IrcAddress> addresses) throws RemoteException {
         for (IrcAddress address : addresses) {

src/com/dmdirc/commandparser/CommandManager.java

 import com.dmdirc.logger.Logger;
 import com.dmdirc.ui.input.TabCompleter;
 import com.dmdirc.util.MapList;
-import com.dmdirc.util.WeakList;
 
 import java.util.ArrayList;
 import java.util.HashMap;
         return getCommand(null, name);
     }
     
+    /**
+     * Retrieves a command of the specified type with the specified name.
+     * 
+     * @param type The type of the command to look for
+     * @param name The name to look for
+     * @return A command with a matching signature, or null if none were found
+     */
     public static Command getCommand(final CommandType type, final String name) {
         final List<Command> res = getCommands(type, name);
         
                 || getCommand(CommandType.TYPE_CHAT, command) != null;
     }
        
+    /**
+     * Retrieves a list of the names of all commands of the specified type.
+     * 
+     * @param type The type of command to list
+     * @return A list of command names
+     */
     public static List<String> getCommandNames(final CommandType type) {
         final List<String> res = new ArrayList<String>();
         
         return res;
     }
     
+    /**
+     * Retrieves a list of all commands of the specified type.
+     * 
+     * @param type The type of command to list
+     * @return A list of commands
+     */    
     public static List<Command> getCommands(final CommandType type) {    
         return getCommands(type, null);
     }
     
+    /**
+     * Retrieves a list of all commands of the specified type, with the
+     * specified name.
+     * 
+     * @param type The type of command to list, or null for all types
+     * @param name The name of the command to look for, or null for any name
+     * @return A list of matching commands
+     */    
     private static List<Command> getCommands(final CommandType type,
             final String name) {
         final List<Command> res = new ArrayList<Command>();

src/com/dmdirc/commandparser/CommandType.java

 import com.dmdirc.commandparser.commands.ServerCommand;
 
 /**
- *
+ * Defines the possible targets for commands.
+ * 
  * @author chris
  */
 public enum CommandType {
     
+    /** A global command, which may be executed anywhere. */
     TYPE_GLOBAL,
+    /** A server command, which only makes sense in the context of a connection. */
     TYPE_SERVER,
+    /** A chat command, which needs a MessageTarget to make sense. */
     TYPE_CHAT,
+    /** A channel command. */
     TYPE_CHANNEL,
+    /** A query command. */
     TYPE_QUERY;
-    
+   
+    /**
+     * Looks up the command type for the specified command, by inspecting its
+     * class.
+     * 
+     * @param command The command to look up
+     * @return The type of the specified command
+     */
     public static CommandType fromCommand(final Command command) {
         if (command instanceof GlobalCommand) {
             return TYPE_GLOBAL;

src/com/dmdirc/commandparser/PopupManager.java

 
 package com.dmdirc.commandparser;
 
-import com.dmdirc.Precondition;
 import com.dmdirc.config.ConfigManager;
-import com.dmdirc.logger.ErrorLevel;
-import com.dmdirc.logger.Logger;
 
-import java.util.LinkedHashMap;
-import java.util.List;
-import java.util.Map;
 
 /**
  * The popup manager manages which commands should be present in popup menus.
      * Configuration data is read from the specified config manager.
      * 
      * @param menuType The type of the menu that is needed
-     * @param configManager The config manager to be used for the mnenu
+     * @param configManager The config manager to be used for the menu
      * @return The PopupMenu that should be displayed
      */
     public static PopupMenu getMenu(final PopupType menuType, final ConfigManager configManager) {
         return getMenu(menuType.toString(), configManager);
     }
     
+    /**
+     * Retrieves the menu with the specified name.
+     * 
+     * @param menuName The name of the menu to read
+     * @param configManager The config manager to be used for the menu
+     * @return The PopupMenu with the specified name
+     */
     private static PopupMenu getMenu(final String menuName, final ConfigManager configManager) {
         final PopupMenu res = new PopupMenu();
         
         return res;
     }
     
+    /**
+     * Creates a PopupMenuItem for the specified item.
+     * 
+     * @param item The item to be turned into a PopupMenuItem
+     * @param configManager The config manager to beused for the menu
+     * @return The corresponding PopupMenuItem
+     */
     private static PopupMenuItem getItem(final String item, final ConfigManager configManager) {
         PopupMenuItem res;
         

src/com/dmdirc/commandparser/PopupMenu.java

 import java.util.List;
 
 /**
- *
+ * Represents an abstract, UI-independent popup menu.
+ * 
  * @author chris
  */
 public class PopupMenu {
     
+    /** The items contained within this popup menu. */
     private final List<PopupMenuItem> items = new ArrayList<PopupMenuItem>();
     
+    /**
+     * Retrieves a list of items contained within this popup menu.
+     * 
+     * @return A list of this popup menu's items.
+     */
     public List<PopupMenuItem> getItems() {
         return items;
     }
 
-    public boolean add(final PopupMenuItem e) {
-        return items.add(e);
+    /**
+     * Adds the specified item to this popup menu.
+     * 
+     * @param e The item to be added to the popup menu.
+     */
+    public void add(final PopupMenuItem e) {
+        items.add(e);
     }
 
-    public boolean addAll(final Collection<? extends PopupMenuItem> c) {
-        return items.addAll(c);
+    /**
+     * Adds all of the items in the specified collection to this popup menu.
+     * 
+     * @param c The collection whose items should be added.
+     */
+    public void addAll(final Collection<? extends PopupMenuItem> c) {
+        items.addAll(c);
     }    
 
 }

src/com/dmdirc/commandparser/PopupMenuItem.java

 package com.dmdirc.commandparser;
 
 /**
- *
+ * Represents an abstract, UI-independent popup menu item.
+ * 
  * @author chris
  */
 public class PopupMenuItem {
-    
+   
+    /** Whether this item is a divider. */
     private boolean divider = false;
+    /** The submenu for this item, if any. */
     private PopupMenu submenu = null;
+    /** The name of this item, if any. */
     private String name;
+    /** The command for this item, if any. */
     private String command;
     
+    /**
+     * Creates a new PopupMenuItem that is used as a divider.
+     */
     public PopupMenuItem() {
         divider = true;
     }
     
+    /**
+     * Creates a new PopupMenuItem that is used as a submenu.
+     * 
+     * @param name The name of the menu item
+     * @param submenu The submenu of this item
+     */
     public PopupMenuItem(final String name, final PopupMenu submenu) {
         this.name = name;
         this.submenu = submenu;
     }
     
+    /**
+     * Creates a new PopupMenuItem that executes a command.
+     * 
+     * @param name The name of the menu item
+     * @param command The command to be executed
+     */
     public PopupMenuItem(final String name, final String command) {
         this.name = name;
         this.command = command;
     }
     
+    /**
+     * Determines if this menu item is a divider or not.
+     * 
+     * @return True if this item is a divider, false otherwise.
+     */
     public boolean isDivider() {
         return divider;
     }
-    
+
+    /**
+     * Determines if this menu item contains a submenu or not.
+     * 
+     * @return True if this item contains a submenu, false otherwise.
+     */    
     public boolean isSubMenu() {
         return submenu != null;
     }
     
+    /**
+     * Retrieves the submenu associated with this item.
+     * 
+     * @return This menu item's submenu.
+     */
     public PopupMenu getSubMenu() {
         return submenu;
     }
     
+    /**
+     * Retrieves the name of this menu item.
+     * 
+     * @return This menu item's name.
+     */
     public String getName() {
         return name;
     }
     
+    /**
+     * Retrieves the command for this menu item, with the specified argumenwits
+     * substituted in.
+     * 
+     * @param arguments The arguments needed for this command
+     * @return The command to be passed to a command parser
+     */
     public String getCommand(final Object... arguments) {
         return CommandManager.getCommandChar() + String.format(command, arguments);
     }

src/com/dmdirc/commandparser/PopupType.java

      * 
      * Expected arguments: the nickname of the user who was clicked on.
      */
-    CHAN_NICKLIST("nick", "chan-nick", "chan-nick-list"),
+    CHAN_NICKLIST,
         
     /**
      * The menu that appears when right clicking in a channel window.
      * 
      * Expected arguments: none.
      */
-    CHAN_CHAN("chan"),
+    CHAN_CHAN,
     
     /**
      * The menu that appears when right clicking in a query window.
      * 
      * Expected arguments: the nickname of the user who the query is with.
      */
-    QUERY_QUERY("nick", "query");
-    
-    private final String[] domains;
-    
-    /**
-     * Instansiates one of the PopupTypes.
-     * 
-     * @param domains The configuration domains used for the type
-     */
-    PopupType(final String ... domains) {
-        this.domains = domains;
-    }
-    
-    /**
-     * Retrieve a list of the domains that should be used by this type.
-     * 
-     * @return This type's domains
-     */
-    public String[] getDomains() {
-        return domains.clone();
-    }
-    
+    QUERY_QUERY;
+       
 }

src/com/dmdirc/commandparser/commands/PreviousCommand.java

 
 import java.util.Date;
 
+/**
+ * Stores information about a previously executed command.
+ * 
+ * @author chris
+ */
 public final class PreviousCommand {
-    
+   
+    /** The full command that was executed. */
     private final String line;
+    
+    /** The timestamp of its execution. */
     private final long time;
     
+    /**
+     * Creates a new record of the specified command.
+     * 
+     * @param line The full command that was executed
+     */
     public PreviousCommand(final String line) {
         this.line = line;
         this.time = new Date().getTime();
     }
     
+    /**
+     * Retrieves the time that the command was executed at.
+     * 
+     * @return The timestamp that the command was executed at
+     */
     public long getTime() {
         return time;
     }
     
+    /**
+     * Retrieves the command that was executed.
+     * 
+     * @return The command that was executed.
+     */
     public String getLine() {
         return line;
     }

src/com/dmdirc/commandparser/commands/global/LoadPlugin.java

 import com.dmdirc.commandparser.CommandManager;
 import com.dmdirc.commandparser.commands.GlobalCommand;
 import com.dmdirc.commandparser.commands.IntelligentCommand;
-import com.dmdirc.plugins.Plugin;
 import com.dmdirc.plugins.PluginInfo;
 import com.dmdirc.plugins.PluginManager;
 import com.dmdirc.ui.input.AdditionalTabTargets;

src/com/dmdirc/commandparser/commands/server/RawServerCommand.java

  */
 public final class RawServerCommand extends ServerCommand {
     
+    /** The name of this raw command. */
     private final String myName;
     
     /**

src/com/dmdirc/config/ConfigTarget.java

     
     /** The possible target types. */
     public static enum TYPE {
-        GLOBALDEFAULT, GLOBAL, THEME, PROFILE, IRCD, NETWORK, SERVER, CHANNEL,
+        /** Client-wide default settings. */
+        GLOBALDEFAULT,
+        /** Client-wide settings. */
+        GLOBAL,
+        /** Settings for a theme. */
+        THEME,
+        /** Settings for a profile. */
+        PROFILE,
+        /** Settings for an IRCd. */
+        IRCD,
+        /** Settings for a network. */
+        NETWORK,
+        /** Settings for a server. */
+        SERVER,
+        /** Settings for a channel. */
+        CHANNEL,
     }
     
     /**
      *
      * @return A string representation of this object
      */
+    @Override
     public String toString() {
         switch (type) {
         case GLOBALDEFAULT:

src/com/dmdirc/config/Identity.java

     /** The configuration details for this identity. */
     protected final Properties properties;
     
+    /** The global config manager. */
     protected ConfigManager globalConfig;
     
     /** The config change listeners for this source. */
         }
     }
     
+    /**
+     * Fires the config changed listener for the specified option after this
+     * identity is reloaded.
+     * 
+     * @param object A string describing the changed option (domain.key)
+     */
     private void fireReloadChange(final Object object) {
         final String string = (String) object;
         final String domain = string.substring(0, string.indexOf('.'));

src/com/dmdirc/config/IdentityManager.java

         }
     }
     
+    /**
+     * Loads an identity from the specified file. If the identity already
+     * exists, it is told to reload instead.
+     * 
+     * @param file The file to load the identity from.
+     */
     private static void loadIdentity(final File file) {
         for (Identity identity : identities) {
             if (file.equals(identity.getFile())) {

src/com/dmdirc/logger/DMDircExceptionHandler.java

     }
     
     /** {@inheritDoc} */
-    public void uncaughtException(final Thread thread, final Throwable throwable) {
-        Logger.appError(ErrorLevel.HIGH, throwable.toString(), throwable);
+    public void uncaughtException(final Thread t, final Throwable e) {
+        Logger.appError(ErrorLevel.HIGH, e.toString(), e);
     }
 }

src/com/dmdirc/themes/Theme.java

 import com.dmdirc.logger.ErrorLevel;
 import com.dmdirc.logger.Logger;
 import com.dmdirc.util.resourcemanager.ZipResourceManager;
-import com.dmdirc.ui.messages.Formatter;
 
 import java.io.File;
 import java.io.IOException;
     /** The file to load the theme from. */
     private final File file;
     
+    /** The resource manager we're using for this theme. */
     private ZipResourceManager rm;
     
     /**

src/com/dmdirc/updater/Update.java

      * An enumeration of possible statuses.
      */
     public static enum STATUS {
+        /** The update is waiting to be started. */
         PENDING,
+        /** The update is currently downloading. */
         DOWNLOADING,
+        /** The update is currently installing. */
         INSTALLING,
+        /** The update has been installed correctly. */
         INSTALLED,
+        /** An error was encountered during update. */
         ERROR,
+        /** A restart is needed to complete the update. */
         RESTART_NEEDED
     }
 

src/com/dmdirc/updater/components/ActionGroupComponent.java

  */
 public class ActionGroupComponent implements UpdateComponent {
     
+    /** The group that this component represents. */
     private ActionGroup group;
     
     /**

src/com/dmdirc/util/Downloader.java

         output.close();
     }    
     
+    /**
+     * Creates an URL connection for the specified URL and data.
+     * 
+     * @param url The URL to connect to
+     * @param postData The POST data to pass to the URL
+     * @return An URLConnection for the specified URL/data
+     * @throws java.net.MalformedURLException If the specified URL is malformed
+     * @throws java.io.IOException If an I/O exception occurs while connecting
+     */
     private static URLConnection getConnection(final String url, final String postData)
             throws MalformedURLException, IOException {
         final URL myUrl = new URL(url);

src/com/dmdirc/util/EquatableWeakReference.java

  * An extension of WeakReference that implements a sane equals and hashcode
  * method.
  * 
+ * @param <T> The type of object that this reference contains
  * @author chris
  */
 public class EquatableWeakReference<T> extends WeakReference<T> {
     
+    /**
+     * Creates a new instance of EquatableWeakReference.
+     * 
+     * @param referent The object that this weak reference should reference.
+     */
     public EquatableWeakReference(T referent) {
         super(referent);
     }

src/com/dmdirc/util/InvalidConfigFileException.java

 package com.dmdirc.util;
 
 /**
- *
+ * Thrown to indicate that a config file is invalid.
  * @author chris
  */
 public class InvalidConfigFileException extends Exception {
     
+    /**
+     * A version number for this class. It should be changed whenever the class
+     * structure is changed (or anything else that would prevent serialized
+     * objects being unserialized with the new class).
+     */    
     private static final long serialVersionUID = 1;
 
+    /**
+     * Creates a new InvalidConfigFileException.
+     * 
+     * @param string A description of the exception that occured.
+     */
     public InvalidConfigFileException(String string) {
         super(string);
     }

src/com/dmdirc/util/IrcAddress.java

  */
 public class IrcAddress implements Serializable {
     
+    /**
+     * A version number for this class. It should be changed whenever the class
+     * structure is changed (or anything else that would prevent serialized
+     * objects being unserialized with the new class).
+     */    
     private final static long serialVersionUID = 1;
 
     /** Whether or not this address uses SSL. */

src/com/dmdirc/util/RollingList.java

 import java.util.List;
 
 /**
- *
+ * Implements a "rolling list". A rolling list has a maximum capacity, and
+ * removes the oldest elements from the list to maintain this capacity.
+ * 
  * @param <T> The type if items that this list contains 
  * @author chris
  */
 public class RollingList<T> {
-    
+   
+    /** The items in this rolling list. */
     private final List<T> items = new ArrayList<T>();
     
+    /** The maximum capacity of this list. */
     private final int capacity;
     
+    /** This list's position pointer. */
     private int position = 0;
     
+    /** Whether or not to add a fake empty item to the end of this list. */
     private boolean addEmpty;
+    /** The "empty" item to be added. */
     private T empty;
     
-    public RollingList(int capacity) {
+    /**
+     * Creates a new RollingList of the specified capacity.
+     * 
+     * @param capacity The capacity of this list.
+     */
+    public RollingList(final int capacity) {
         this.capacity = capacity;
         this.addEmpty = false;
     }
 
-    public RollingList(int capacity, T empty) {
+    /**
+     * Creates a new RollingList of the specified capacity, with the specified
+     * "empty" element appended to the end.
+     * 
+     * @param capacity The capacity of this list.
+     * @param empty The "empty" element to be added
+     */    
+    public RollingList(final int capacity, final T empty) {
         this.capacity = capacity;
         this.addEmpty = true;
         this.empty = empty;
     }
 
-    public boolean remove(Object o) {
+    /**
+     * Removes the specified element from this list.
+     * 
+     * @param o The object to be removed from the list.
+     * @return True if the list contained the specified element, false otherwise.
+     */
+    public boolean remove(final Object o) {
         return items.remove(o);
     }
 
+    /**
+     * Determines if this list is currently empty.
+     * 
+     * @return True if the list is empty, false otherwise.
+     */
     public boolean isEmpty() {
         return items.isEmpty();
     }
 
-    public T get(int index) {
+    /**
+     * Retrieves the item at the specified index in this list.
+     * 
+     * @param index The index to look up
+     * @return The item at the specified index
+     */
+    public T get(final int index) {
         return items.get(index);
     }
 
-    public boolean contains(Object o) {
+    /**
+     * Determines if this list contains the specified object.
+     * 
+     * @param o The object to be checked
+     * @return True if this list contains the item, false otherwise.
+     */
+    public boolean contains(final Object o) {
         return items.contains(o);
     }
 
+    /**
+     * Clears all items from this list.
+     */
     public void clear() {
         items.clear();
     }  
     
+    /**
+     * Adds the specified item to this list. If the list has reached its
+     * maximum capacity, this method will remove elements from the start of the
+     * list until there is sufficient room for the new element.
+     * 
+     * @param e The element to be added to the list.
+     * @return True
+     */
     public boolean add(T e) {
         while (items.size() > capacity - 1) {
             items.remove(0);
         return items.add(e);
     }
     
+    /**
+     * Retrieves the current position within the list.
+     * 
+     * @return This list's positional pointer
+     */
     public int getPosition() {
         return position;
     }
 
+    /**
+     * Sets the positional pointer of this list.
+     * 
+     * @param position The new position
+     */
     public void setPosition(int position) {
         this.position = position;
     }    
     
+    /**
+     * Determines if there is an element after the positional pointer of the list.
+     * 
+     * @return True if there is an element, false otherwise.
+     */
     public boolean hasNext() {
         return (items.size() > position + 1) || ((items.size() > position) && addEmpty);
     }
     
+    /**
+     * Retrieves the element after the positional pointer of the list.
+     * 
+     * @return The next element in the list
+     */
     public T getNext() {
         if (items.size() > position + 1 || !addEmpty) {
             return get(++position);
         }
     }
     
+    /**
+     * Determines if there is an element befpre the positional pointer of the list.
+     * 
+     * @return True if there is an element, false otherwise.
+     */    
     public boolean hasPrevious() {
         return 0 < position;
     }
     
+    /**
+     * Retrieves the element before the positional pointer of the list.
+     * 
+     * @return The previous element in the list
+     */    
     public T getPrevious() {
         return get(--position);
     }    
     
+    /**
+     * Sets the positional pointer of this list to the end.
+     */
     public void seekToEnd() {
         position = items.size();
     }
     
+    /**
+     * Sets the positional pointer of this list to the start.
+     */
     public void seekToStart() {
         position = 0;
     }
     
+    /**
+     * Retrieves a list of items that this rolling list contains.
+     * 
+     * @return A list of items in this rolling list.
+     */
     public List<T> getList() {
         return new ArrayList<T>(items);
     }

src/com/dmdirc/util/StringTranscoder.java

  */
 public class StringTranscoder {
    
+    /** The charset that is used by this transcoder. */
     private final Charset charset;
     
     /**

src/com/dmdirc/util/WeakList.java

 import java.util.ListIterator;
 
 /**
- *
- * @param <T>
+ * Implements a list of weak references. The weak references (and subsequent
+ * garbage collection) are handled transparently.
+ * 
+ * @param <T> The type of object that this list will contain.
  * @author chris
  */
 public class WeakList<T> implements List<T> {
 
+    /** The items in this list. */
     private final List<WeakReference<T>> list = new ArrayList<WeakReference<T>>();
 
+    /**
+     * Creates a new instance of WeakList.
+     */
     public WeakList() {
         super();
     }
 
+    /**
+     * Removes any entries from the list that have been GC'd.
+     */
     private void cleanUp() {
         for (int i = 0; i < list.size(); i++) {
             if (list.get(i).get() == null) {
         }
     }
 
+    /**
+     * Dereferences the specified list of WeakReferences to get a plain List.
+     * 
+     * @param list The list to be dereferenced
+     * @return A list containing the items referenced by the specified list
+     */
     private List<T> dereferenceList(final List<WeakReference<T>> list) {
         final List<T> res = new ArrayList<T>();
 
         return res;
     }
 
+    /**
+     * Creates a new collection of weak references to elements in the specified
+     * collection.
+     * 
+     * @param c The collection whose elements should be referenced
+     * @return A copy of the specified collection, with each item wrapped in
+     * a weak reference.
+     */
     @SuppressWarnings(value = "unchecked")
     private Collection<WeakReference<T>> referenceCollection(final Collection<?> c) {
         final Collection<WeakReference<T>> res = new ArrayList<WeakReference<T>>();