add comments

src/main/java/com/github/nkzawa/socketio/client/IO.java

@@ -9,10 +9,14 @@ import java.net.URISyntaxException;
 import java.net.URL;
 import java.util.concurrent.ConcurrentHashMap;
 
+
 public class IO {
 
     private static final ConcurrentHashMap<String, Manager> managers = new ConcurrentHashMap<String, Manager>();
 
+    /**
+     * Protocol version.
+     */
     public static int protocol = Parser.protocol;
 
 
@@ -30,6 +34,14 @@ public class IO {
         return socket(uri, null);
     }
 
+    /**
+     * Initializes a {@link Socket} from an existing {@link Manager} for multiplexing.
+     *
+     * @param uri uri to connect.
+     * @param opts options for socket.
+     * @return {@link Socket} instance.
+     * @throws URISyntaxException
+     */
     public static Socket socket(URI uri, Options opts) throws URISyntaxException {
         if (opts == null) {
             opts = new Options();
@@ -62,7 +74,12 @@ public class IO {
     public static class Options extends com.github.nkzawa.engineio.client.Socket.Options {
 
         public boolean forceNew;
+
+        /**
+         * Whether to enable multiplexing. Default is true.
+         */
         public boolean multiplex = true;
+
         public boolean reconnection;
         public int reconnectionAttempts;
         public long reconnectionDelay;

src/main/java/com/github/nkzawa/socketio/client/Manager.java

@@ -11,25 +11,54 @@ import java.util.Queue;
 import java.util.concurrent.*;
 import java.util.logging.Logger;
 
+
+/**
+ * Manager class represents a connection to a given Socket.IO server.
+ */
 public class Manager extends Emitter {
 
     private static final Logger logger = Logger.getLogger(Manager.class.getName());
 
-    /*package*/ static final int CLOSED = 0;
+    /*package*/ enum ReadyState {
-    /*package*/ static final int OPENING = 1;
+        CLOSED, OPENING, OPEN
-    /*package*/ static final int OPEN = 2;
+    }
 
+    /**
+     * Called on a successful connection.
+     */
     public static final String EVENT_OPEN = "open";
+
+    /**
+     * Called on a disconnection.
+     */
     public static final String EVENT_CLOSE = "close";
+
     public static final String EVENT_PACKET = "packet";
     public static final String EVENT_ERROR = "error";
+
+    /**
+     * Called on a connection error.
+     */
     public static final String EVENT_CONNECT_ERROR = "connect_error";
+
+    /**
+     * Called on a connection timeout.
+     */
     public static final String EVENT_CONNECT_TIMEOUT = "connect_timeout";
+
+    /**
+     * Called on a successful reconnection.
+     */
     public static final String EVENT_RECONNECT = "reconnect";
-    public static final String EVENT_RECONNECT_FAILED = "reconnect_failed";
+
+    /**
+     * Called on a reconnection attempt error.
+     */
     public static final String EVENT_RECONNECT_ERROR = "reconnect_error";
 
-    /*package*/ int readyState = CLOSED;
+    public static final String EVENT_RECONNECT_FAILED = "reconnect_failed";
+
+    /*package*/ ReadyState readyState = ReadyState.CLOSED;
 
     private boolean _reconnection;
     private boolean skipReconnect;
@@ -126,16 +155,22 @@ public class Manager extends Emitter {
         return open(null);
     }
 
+    /**
+     * Connects the client.
+     *
+     * @param fn callback.
+     * @return a reference to this object.
+     */
     public Manager open(final OpenCallback fn) {
         EventThread.exec(new Runnable() {
             @Override
             public void run() {
-                if (Manager.this.readyState == OPEN && !Manager.this.reconnecting) return;
+                if (Manager.this.readyState == ReadyState.OPEN && !Manager.this.reconnecting) return;
 
                 final com.github.nkzawa.engineio.client.Socket socket = Manager.this.engine;
                 final Manager self = Manager.this;
 
-                Manager.this.readyState = OPENING;
+                Manager.this.readyState = ReadyState.OPENING;
 
                 final On.Handle openSub = On.on(socket, Engine.EVENT_OPEN, new Listener() {
                     @Override
@@ -201,7 +236,7 @@ public class Manager extends Emitter {
     private void onopen() {
         this.cleanup();
 
-        this.readyState = OPEN;
+        this.readyState = ReadyState.OPEN;
         this.emit(EVENT_OPEN);
 
         final com.github.nkzawa.engineio.client.Socket socket = this.engine;
@@ -233,6 +268,12 @@ public class Manager extends Emitter {
         this.emit(EVENT_ERROR, err);
     }
 
+    /**
+     * Initializes {@link Socket} instances for each namespaces.
+     *
+     * @param nsp namespace.
+     * @return a socket instance for the namespace.
+     */
     public Socket socket(String nsp) {
         Socket socket = this.nsps.get(nsp);
         if (socket == null) {

src/main/java/com/github/nkzawa/socketio/client/Socket.java

@@ -11,17 +11,37 @@ import com.google.gson.JsonElement;
 import java.util.*;
 import java.util.logging.Logger;
 
+/**
+ * The socket class for Socket.IO Client.
+ */
 public class Socket extends Emitter {
 
     private static final Logger logger = Logger.getLogger(Socket.class.getName());
 
     private static final Gson gson = new Gson();
 
+    /**
+     * Called on a connection.
+     */
     public static final String EVENT_CONNECT = "connect";
+
+    /**
+     * Called on a disconnection.
+     */
     public static final String EVENT_DISCONNECT = "disconnect";
-    public static final String EVENT_MESSAGE = "message";
+
+    /**
+     * Called on a connection error.
+     *
+     * <p>Parameters:</p>
+     * <ul>
+     *   <li>(Exception) error data.</li>
+     * </ul>
+     */
     public static final String EVENT_ERROR = "error";
 
+    public static final String EVENT_MESSAGE = "message";
+
     private static List<String> events = new ArrayList<String>() {{
         add(EVENT_CONNECT);
         add(EVENT_DISCONNECT);
@@ -43,6 +63,9 @@ public class Socket extends Emitter {
         this.nsp = nsp;
     }
 
+    /**
+     * Connects the socket.
+     */
     public void open() {
         EventThread.exec(new Runnable() {
             @Override
@@ -62,16 +85,25 @@ public class Socket extends Emitter {
                         }
                     }));
                 }};
-                if (Socket.this.io.readyState == Manager.OPEN) Socket.this.onopen();
+                if (Socket.this.io.readyState == Manager.ReadyState.OPEN) Socket.this.onopen();
                 io.open();
             }
         });
     }
 
+    /**
+     * Connects the socket.
+     */
     public void connect() {
         this.open();
     }
 
+    /**
+     * Send messages.
+     *
+     * @param args data to send.
+     * @return a reference to this object.
+     */
     public Socket send(final Object... args) {
         EventThread.exec(new Runnable() {
             @Override
@@ -82,6 +114,13 @@ public class Socket extends Emitter {
         return this;
     }
 
+    /**
+     * Emits an event. When you pass {@link Ack} at the last argument, then the acknowledge is done.
+     *
+     * @param event an event name.
+     * @param args data to send.
+     * @return a reference to this object.
+     */
     @Override
     public Emitter emit(final String event, final Object... args) {
         EventThread.exec(new Runnable() {
@@ -107,12 +146,12 @@ public class Socket extends Emitter {
     }
 
     /**
-     * emit with an ack callback
+     * Emits an event with an acknowledge.
      *
-     * @param event
+     * @param event an event name
-     * @param args
+     * @param args data to send.
-     * @param ack
+     * @param ack the acknowledgement to be called
-     * @return
+     * @return a reference to this object.
      */
     public Emitter emit(final String event, final Object[] args, final Ack ack) {
         EventThread.exec(new Runnable() {
@@ -271,6 +310,11 @@ public class Socket extends Emitter {
         this.io.destroy(this);
     }
 
+    /**
+     * Disconnects the socket.
+     *
+     * @return a reference to this object.
+     */
     public Socket close() {
         EventThread.exec(new Runnable() {
             @Override
@@ -288,6 +332,11 @@ public class Socket extends Emitter {
         return this;
     }
 
+    /**
+     * Disconnects the socket.
+     *
+     * @return a reference to this object.
+     */
     public Socket disconnect() {
         return this.close();
     }
@@ -309,6 +358,9 @@ public class Socket extends Emitter {
     }
 
 
+    /**
+     * Acknowledgement.
+     */
     public static interface Ack {
 
         public void call(Object... args);

src/main/java/com/github/nkzawa/socketio/parser/Parser.java

@@ -16,13 +16,36 @@ public class Parser {
     private static final Gson gson = new Gson();
     private static final JsonParser parser = new JsonParser();
 
+    /**
+     * Packet type `connect`.
+     */
     public static final int CONNECT = 0;
+
+    /**
+     * Packet type `disconnect`.
+     */
     public static final int DISCONNECT = 1;
+
+    /**
+     * Packet type `event`.
+     */
     public static final int EVENT = 2;
+
+    /**
+     * Packet type `ack`.
+     */
     public static final int ACK = 3;
+
+    /**
+     * Packet type `error`.
+     */
     public static final int ERROR = 4;
 
     public static int protocol = 1;
+
+    /**
+     * Packet types.
+     */
     public static List<String > types = new ArrayList<String>() {{
         add("CONNECT");
         add("DISCONNECT");