Misc tidying and lots of javadoc

src/uk/co/md87/evetool/Main.java

@@ -33,6 +33,8 @@ import uk.co.md87.evetool.api.util.TableCreator;
 import uk.co.md87.evetool.ui.MainWindow;
 
 /**
+ * Main class for the program. Handles initialisation of the core assets
+ * and UI.
  *
  * @author chris
  */
@@ -45,6 +47,8 @@ public class Main {
     private static final String[] TABLES = new String[]{"Accounts"};
 
     /**
+     * Main program entry point.
+     * 
      * @param args the command line arguments
      */
     public static void main(final String[] args) {

src/uk/co/md87/evetool/api/io/QueueSizeListener.java

@@ -23,12 +23,21 @@
 package uk.co.md87.evetool.api.io;
 
 /**
- *
- * TODO: Document QueueSizeListener
+ * An interface to be implemented by objects that wish to be notified when
+ * the size of the queue of API requests changes. The queue and notification
+ * of listeners is handled by the {@link ApiDownloader}.
+ * 
  * @author chris
  */
 public interface QueueSizeListener {
 
+    /**
+     * Called whenever the queue size changes (in either direction), and
+     * immediately after the listener is registered with the
+     * {@link ApiDownloader}.
+     *
+     * @param size The new size of the request queue
+     */
     void queueSizeUpdate(final int size);
 
 }

src/uk/co/md87/evetool/api/parser/ApiParser.java

@@ -33,19 +33,34 @@ import org.jdom.JDOMException;
 import org.jdom.input.SAXBuilder;
 
 /**
- *
- * TODO: Document ApiParser
+ * Parses the result of an API request.
+ * 
  * @author chris
  */
 public class ApiParser {
 
+    /**
+     * Parses the specified data into a tree of {@link ApiResult}s.
+     *
+     * @param data The data to be parsed
+     * @return A representation of the data as a tree of ApiResults
+     * @throws IOException If the data cannot be read correctly
+     * @throws JDOMException If the XML data cannot be parsed correctly
+     * @throws ParserException If the API data cannot be processed correctly
+     */
     public ApiResult parseResult(final String data) throws IOException, JDOMException,
             ParserException {
         return parseResult(new SAXBuilder().build(new StringReader(data)));
     }
 
-    public ApiResult parseResult(final Document doc) throws IOException, JDOMException,
-            ParserException {
+    /**
+     * Parses the specified document into a tree of {@link ApiResult}s.
+     *
+     * @param doc The document to be parsed
+     * @return A representation of the document as a tree of ApiResults
+     * @throws ParserException If the API data cannot be processed correctly
+     */
+    public ApiResult parseResult(final Document doc) throws ParserException {
         final Element root = doc.getRootElement();
 
         if (!"eveapi".equals(root.getName())) {
@@ -58,6 +73,13 @@ public class ApiParser {
         return result;
     }
 
+    /**
+     * Adds the specified XML {@link Element} and its children to the specified
+     * {@link ApiElement}.
+     *
+     * @param result The ApiElement to append the results to
+     * @param element The XML Element to be parsed and added
+     */
     @SuppressWarnings("unchecked")
     protected void addElements(final ApiElement result, final Element element) {
         for (Attribute attr : (List<Attribute>) element.getAttributes()) {

src/uk/co/md87/evetool/api/parser/NamedApiElement.java

@@ -23,18 +23,30 @@
 package uk.co.md87.evetool.api.parser;
 
 /**
- *
- * TODO: Document NamedApiElement
+ * An extension of a standard {@link ApiElement} that has a name associated with
+ * it.
+ * 
  * @author chris
  */
 public class NamedApiElement extends ApiElement {
 
+    /** The name of this ApiElement. */
     private final String name;
 
-    public NamedApiElement(String name) {
+    /**
+     * Creates a new NamedApiElement with the specified name.
+     *
+     * @param name The name of the ApiElement
+     */
+    public NamedApiElement(final String name) {
         this.name = name;
     }
 
+    /**
+     * Retrieves the name of this NamedApiElement.
+     *
+     * @return This element's name
+     */
     public String getName() {
         return name;
     }

src/uk/co/md87/evetool/api/parser/ParserException.java

@@ -23,8 +23,9 @@
 package uk.co.md87.evetool.api.parser;
 
 /**
- *
- * TODO: Document ParserException
+ * Indicates that a problem was encountered when parsing the XML API result
+ * in line with the published EVE API specifications.
+ * 
  * @author chris
  */
 public class ParserException extends Exception {
@@ -36,11 +37,23 @@ public class ParserException extends Exception {
      */
     private static final long serialVersionUID = 10;
 
-    public ParserException(String message, Throwable cause) {
+    /**
+     * Creates a new ParserException caused by the specified {@link Throwable},
+     * with the specified error message.
+     *
+     * @param message A textual description of the exception
+     * @param cause The exception or error that caused the parser failure
+     */
+    public ParserException(final String message, final Throwable cause) {
         super(message, cause);
     }
 
-    public ParserException(String message) {
+    /**
+     * Creates a new ParserException with the specified error message.
+     *
+     * @param message A textual description of the exception
+     */
+    public ParserException(final String message) {
         super(message);
     }
 

src/uk/co/md87/evetool/api/wrappers/CharacterList.java

@@ -23,15 +23,14 @@
 package uk.co.md87.evetool.api.wrappers;
 
 import java.util.ArrayList;
-import java.util.Map;
 
 import uk.co.md87.evetool.api.parser.ApiElement;
 import uk.co.md87.evetool.api.wrappers.data.BasicCharInfo;
 import uk.co.md87.evetool.api.wrappers.data.BasicCorpInfo;
 
 /**
- *
- * TODO: Document CharacterList
+ * A list of characters associated with a particular account.
+ * 
  * @author chris
  */
 public class CharacterList extends ArrayList<BasicCharInfo> {
@@ -43,14 +42,26 @@ public class CharacterList extends ArrayList<BasicCharInfo> {
      */
     private static final long serialVersionUID = 10;
 
+    /**
+     * Creates a new character list from the specified result set.
+     *
+     * @param resultElement The result element of a character list query.
+     */
     public CharacterList(final ApiElement resultElement) {
         super();
 
-        for (ApiElement child : resultElement.getChild("rowset").getChildren()) {
+        for (ApiElement child : resultElement.getRowset("characters")) {
             add(getCharInfo(child));
         }
     }
 
+    /**
+     * Constructs a {@link BasicCharInfo} object corresponding to the data in
+     * the specified row.
+     *
+     * @param row The row of data to be parsed
+     * @return A corresponding BasicCharInfo object
+     */
     protected BasicCharInfo getCharInfo(final ApiElement row) {
         final BasicCorpInfo corpInfo = new BasicCorpInfo(
                 row.getStringAttribute("corporationName"),

src/uk/co/md87/evetool/api/wrappers/data/BasicCharInfo.java

@@ -22,6 +22,8 @@
 
 package uk.co.md87.evetool.api.wrappers.data;
 
+import uk.co.md87.evetool.ui.listable.Retrievable;
+
 /**
  *
  * TODO: Document BasicCharInfo
@@ -39,18 +41,22 @@ public class BasicCharInfo {
         this.corp = corp;
     }
 
+    @Retrievable(deferred=true, name="Corporation")
     public BasicCorpInfo getCorp() {
         return corp;
     }
 
+    @Retrievable
     public int getId() {
         return id;
     }
 
+    @Retrievable
     public String getName() {
         return name;
     }
 
+    /** {@inheritDoc} */
     @Override
     public String toString() {
         return "[" + name + " (" + id + ") in " + corp + "]";

src/uk/co/md87/evetool/api/wrappers/data/BasicCloneInfo.java

@@ -22,6 +22,8 @@
 
 package uk.co.md87.evetool.api.wrappers.data;
 
+import uk.co.md87.evetool.ui.listable.Retrievable;
+
 /**
  *
  * TODO: Document BasicCloneInfo
@@ -37,10 +39,12 @@ public class BasicCloneInfo {
         this.spLimit = spLimit;
     }
 
+    @Retrievable
     public String getName() {
         return name;
     }
 
+    @Retrievable(name="Skillpoint limit")
     public long getSpLimit() {
         return spLimit;
     }

src/uk/co/md87/evetool/api/wrappers/data/BasicCorpInfo.java

@@ -22,6 +22,8 @@
 
 package uk.co.md87.evetool.api.wrappers.data;
 
+import uk.co.md87.evetool.ui.listable.Retrievable;
+
 /**
  *
  * TODO: Document BasicCorpInfo
@@ -37,14 +39,17 @@ public class BasicCorpInfo {
         this.id = id;
     }
 
+    @Retrievable
     public int getId() {
         return id;
     }
 
+    @Retrievable
     public String getName() {
         return name;
     }
 
+    /** {@inheritDoc} */
     @Override
     public String toString() {
         return "[" + name + " (" + id + ")]";

src/uk/co/md87/evetool/api/wrappers/data/CertClass.java

@@ -23,6 +23,7 @@
 package uk.co.md87.evetool.api.wrappers.data;
 
 import java.util.List;
+import uk.co.md87.evetool.ui.listable.Retrievable;
 
 /**
  *
@@ -46,10 +47,12 @@ public class CertClass {
         return certificates;
     }
 
+    @Retrievable
     public int getId() {
         return id;
     }
 
+    @Retrievable
     public String getName() {
         return name;
     }

src/uk/co/md87/evetool/api/wrappers/data/CertInfo.java

@@ -23,6 +23,7 @@
 package uk.co.md87.evetool.api.wrappers.data;
 
 import java.util.List;
+import uk.co.md87.evetool.ui.listable.Retrievable;
 
 /**
  *
@@ -53,18 +54,22 @@ public class CertInfo {
         return certReqs;
     }
 
+    @Retrievable(name="Issuing corporation ID")
     public int getCorp() {
         return corp;
     }
 
+    @Retrievable(name="Description")
     public String getDesc() {
         return desc;
     }
 
+    @Retrievable
     public int getGrade() {
         return grade;
     }
 
+    @Retrievable
     public int getId() {
         return id;
     }
@@ -73,6 +78,7 @@ public class CertInfo {
         return skillReqs;
     }
 
+    /** {@inheritDoc} */
     @Override
     public String toString() {
         return "[" + id + ": grade " + grade + "]";

src/uk/co/md87/evetool/api/wrappers/data/Implant.java

@@ -22,6 +22,8 @@
 
 package uk.co.md87.evetool.api.wrappers.data;
 
+import uk.co.md87.evetool.ui.listable.Retrievable;
+
 /**
  *
  * TODO: Document Implant
@@ -39,14 +41,17 @@ public class Implant {
         this.bonus = bonus;
     }
 
+    @Retrievable
     public Attribute getAttribute() {
         return attribute;
     }
 
+    @Retrievable
     public int getBonus() {
         return bonus;
     }
 
+    @Retrievable
     public String getName() {
         return name;
     }

src/uk/co/md87/evetool/ui/ContentPanel.java

@@ -34,6 +34,7 @@ import uk.co.md87.evetool.ui.data.AccountChar;
 
 /**
  *
+ * TODO: Document ContentPanel
  * @author chris
  */
 public class ContentPanel extends JPanel {

src/uk/co/md87/evetool/ui/StatusPanel.java

@@ -23,17 +23,20 @@
 package uk.co.md87.evetool.ui;
 
 import java.awt.Color;
+
 import javax.swing.BorderFactory;
 import javax.swing.JLabel;
 import javax.swing.JPanel;
+
 import net.miginfocom.swing.MigLayout;
+
 import uk.co.md87.evetool.Main;
 import uk.co.md87.evetool.api.io.ApiDownloader;
 import uk.co.md87.evetool.api.io.QueueSizeListener;
 
 /**
- *
- * TODO: Document StatusPanel
+ * Panel which shows status information at the bottom of the main window.
+ * 
  * @author chris
  */
 public class StatusPanel extends JPanel implements QueueSizeListener {
@@ -45,8 +48,14 @@ public class StatusPanel extends JPanel implements QueueSizeListener {
      */
     private static final long serialVersionUID = 10;
 
+    /** Labels used to display various pieces of information. */
     private final JLabel leftLabel, centreLabel, rightLabel;
 
+    /**
+     * Creates a new status panel for the specified window.
+     *
+     * @param window The {@link MainWindow} that this status panel is for
+     */
     public StatusPanel(final MainWindow window) {
         super(new MigLayout());
 
@@ -63,9 +72,11 @@ public class StatusPanel extends JPanel implements QueueSizeListener {
         ApiDownloader.addQueueSizeListener(this);
     }
 
+    /** {@inheritDoc} */
+    @Override
     public void queueSizeUpdate(final int size) {
         centreLabel.setText(size == 0 ? "" : 
-            (size + " queued request" + (size == 1 ? "" : "s")));
+            (size + " API quer" + (size == 1 ? "y" : "ies") + " pending"));
     }
 
 }

src/uk/co/md87/evetool/ui/components/AddButton.java

@@ -32,6 +32,7 @@ import javax.swing.JButton;
 
 /**
  *
+ * TODO: Document AddButton
  * @author chris
  */
 public class AddButton extends JButton {

src/uk/co/md87/evetool/ui/listable/Retrievable.java

@@ -28,16 +28,33 @@ import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
 /**
- *
- * TODO: Document Retrievable
+ * Designates that the return type of the method is retrievable for use in a
+ * {@link Listable}.
+ * 
  * @author chris
  */
 @Retention(RetentionPolicy.RUNTIME)
 @Target(ElementType.METHOD)
 public @interface Retrievable {
 
+    /**
+     * Indicates that the return type of the method should be scanned for
+     * other retrievable methods, instead of just using the result directly.
+     * If the {@link #name()} property is specified as well, the name is used
+     * as a prefix for the methods found in the returned retrievable.
+     * 
+     * @return True if the return type should be scanned for 'deferred'
+     * retrievables, false if the result should be used verbatim
+     */
     boolean deferred() default false;
-    
+
+    /**
+     * A custom name for the retrievable method. If no name is specified, it is
+     * inferred from the method name by stripping prefixes such as 'get' and
+     * inserting spaces before CamelCase words.
+     * 
+     * @return The custom name for the method
+     */
     String name() default "";
     
 }

src/uk/co/md87/evetool/ui/listable/UpdateListener.java

@@ -23,11 +23,17 @@
 package uk.co.md87.evetool.ui.listable;
 
 /**
- *
- * TODO: Document UpdateListener
+ * Interface to be implemented by objects that wish to be notified when a
+ * {@link Listable} has been updated in some way.
+ * 
  * @author chris
  */
 public interface UpdateListener {
 
+    /**
+     * Called when a {@link Listable} has been updated.
+     *
+     * @param listable The object that was updated
+     */
     void listableUpdated(final Listable listable);
 }

src/uk/co/md87/evetool/ui/pages/SkillPage.java

@@ -65,8 +65,6 @@ public class SkillPage extends Page {
         this.factory = factory;
 
         setLayout(new MigLayout("fillx, wrap 1"));
-
-        add(new JLabel("Skills! Moo!"));
     }
 
     /** {@inheritDoc} */