More documentation

Socket.IO-Client-Swift.xcodeproj/project.pbxproj

@@ -990,7 +990,7 @@
 				ONLY_ACTIVE_ARCH = YES;
 				PRODUCT_NAME = SocketIO;
 				SWIFT_OPTIMIZATION_LEVEL = "-Onone";
-				SWIFT_VERSION = 3.0;
+				SWIFT_VERSION = 4.0;
 				TVOS_DEPLOYMENT_TARGET = 9.0;
 				WATCHOS_DEPLOYMENT_TARGET = 2.0;
 			};
@@ -1029,7 +1029,7 @@
 				MACOSX_DEPLOYMENT_TARGET = 10.10;
 				PRODUCT_NAME = SocketIO;
 				SWIFT_OPTIMIZATION_LEVEL = "-Owholemodule";
-				SWIFT_VERSION = 3.0;
+				SWIFT_VERSION = 4.0;
 				TVOS_DEPLOYMENT_TARGET = 9.0;
 				WATCHOS_DEPLOYMENT_TARGET = 2.0;
 			};

Source/SocketIO/Client/SocketIOClient.swift

@@ -64,7 +64,9 @@ open class SocketIOClient : NSObject, SocketIOClientSpec, SocketEngineClient, So
     @objc
     public var handleQueue = DispatchQueue.main
 
-    /// The namespace for this client.
+    /// The namespace that this socket is currently connected to.
+    ///
+    /// **Must** start with a `/`.
     @objc
     public var nsp = "/"
 
@@ -93,6 +95,11 @@ open class SocketIOClient : NSObject, SocketIOClientSpec, SocketEngineClient, So
     public var socketURL: URL
 
     var ackHandlers = SocketAckManager()
+
+    /// A list of packets that are waiting for binary data.
+    ///
+    /// The way that socket.io works all data should be sent directly after each packet.
+    /// So this should ideally be an array of one packet waiting for data.
     var waitingPackets = [SocketPacket]()
 
     private(set) var currentAck = -1
@@ -172,7 +179,9 @@ open class SocketIOClient : NSObject, SocketIOClientSpec, SocketEngineClient, So
         engine = SocketEngine(client: self, url: socketURL, config: config)
     }
 
-    /// Connect to the server.
+    /// Connect to the server. The same as calling `connect(timeoutAfter:withHandler:)` with a timeout of 0.
+    ///
+    /// Only call after adding your event listeners, unless you know what you're doing.
     @objc
     open func connect() {
         connect(timeoutAfter: 0, withHandler: nil)
@@ -180,6 +189,8 @@ open class SocketIOClient : NSObject, SocketIOClientSpec, SocketEngineClient, So
 
     /// Connect to the server. If we aren't connected after `timeoutAfter` seconds, then `withHandler` is called.
     ///
+    /// Only call after adding your event listeners, unless you know what you're doing.
+    ///
     /// - parameter timeoutAfter: The number of seconds after which if we are not connected we assume the connection
     ///                           has failed. Pass 0 to never timeout.
     /// - parameter withHandler: The handler to call when the client fails to connect.
@@ -219,6 +230,8 @@ open class SocketIOClient : NSObject, SocketIOClientSpec, SocketEngineClient, So
         return OnAckCallback(ackNumber: currentAck, items: items, socket: self)
     }
 
+    /// Called when the client connects to a namespace. If the client was created with a namespace upfront,
+    /// then this is only called when the client connects to that namespace.
     func didConnect(toNamespace namespace: String) {
         DefaultSocketLogger.Logger.log("Socket connected", type: SocketIOClient.logType)
 
@@ -227,6 +240,7 @@ open class SocketIOClient : NSObject, SocketIOClientSpec, SocketEngineClient, So
         handleClientEvent(.connect, data: [namespace])
     }
 
+    /// Called when the client has disconnected from socket.io.
     func didDisconnect(reason: String) {
         guard status != .disconnected else { return }
 
@@ -437,7 +451,7 @@ open class SocketIOClient : NSObject, SocketIOClientSpec, SocketEngineClient, So
         handleEvent(event.rawValue, data: data, isInternalMessage: true)
     }
 
-    /// Leaves nsp and goes back to the default namespace.
+    /// Call when you wish to leave a namespace and return to the default namespace.
     @objc
     open func leaveNamespace() {
         if nsp != "/" {

Source/SocketIO/Client/SocketIOClientSpec.swift

@@ -25,20 +25,52 @@
 import Dispatch
 
 protocol SocketIOClientSpec : class {
+    /// The queue that all interaction with the client must be on.
     var handleQueue: DispatchQueue { get set }
+
+    /// The namespace that this socket is currently connected to.
+    ///
+    /// **Must** start with a `/`.
     var nsp: String { get set }
+
+    /// A list of packets that are waiting for binary data.
+    ///
+    /// The way that socket.io works all data should be sent directly after each packet.
+    /// So this should ideally be an array of one packet waiting for data.
     var waitingPackets: [SocketPacket] { get set }
 
+    /// Called when the client connects to a namespace. If the client was created with a namespace upfront,
+    /// then this is only called when the client connects to that namespace.
     func didConnect(toNamespace namespace: String)
+
+    /// Called when the client has disconnected from socket.io.
     func didDisconnect(reason: String)
+
+    /// Called when the client encounters an error.
     func didError(reason: String)
+
+    /// Called when socket.io has acked one of our emits. Causes the corresponding ack callback to be called.
     func handleAck(_ ack: Int, data: [Any])
+
+    /// Called when we get an event from socket.io.
     func handleEvent(_ event: String, data: [Any], isInternalMessage: Bool, withAck ack: Int)
+
+    /// Called on socket.io events.
     func handleClientEvent(_ event: SocketClientEvent, data: [Any])
+
+    /// Call when you wish to leave a namespace and return to the default namespace.
+    func leaveNamespace()
+
+    /// Joins `namespace`.
+    ///
+    /// **Do not use this to join the default namespace.** Instead call `leaveNamespace`.
+    ///
+    /// - parameter namespace: The namespace to join.
     func joinNamespace(_ namespace: String)
 }
 
 extension SocketIOClientSpec {
+    /// Default implementation.
     func didError(reason: String) {
         DefaultSocketLogger.Logger.error("\(reason)", type: "SocketIOClient")
 

Source/Starscream

@@ -1 +1 @@
-Subproject commit f7e28f24ae20898da5804079319da52682bb9212
+Subproject commit 9ecc44c2da053b1c4ff0ac505fe1d43a793d0b45