Document ack types

Source/SocketAckEmitter.swift

@@ -25,10 +25,14 @@
 import Dispatch
 import Foundation
 
+/// A class that represents a waiting ack call.
+///
+/// **NOTE**: You should not store this beyond the life of the event handler.
 public final class SocketAckEmitter : NSObject {
     let socket: SocketIOClient
     let ackNum: Int
 
+    /// If true, this handler is expecting to be acked. Call `with(_: SocketData...)` to ack.
     public var expected: Bool {
         return ackNum != -1
     }
@@ -38,12 +42,20 @@ public final class SocketAckEmitter : NSObject {
         self.ackNum = ackNum
     }
 
+    // MARK: Methods
+
+    /// Call to ack receiving this event.
+    ///
+    /// - parameter items: A variable number of items to send when acking.
     public func with(_ items: SocketData...) {
         guard ackNum != -1 else { return }
 
         socket.emitAck(ackNum, with: items)
     }
 
+    /// Call to ack receiving this event.
+    ///
+    /// - parameter items: An array of items to send when acking. Use `[]` to send nothing.
     public func with(_ items: [Any]) {
         guard ackNum != -1 else { return }
 
@@ -52,6 +64,14 @@ public final class SocketAckEmitter : NSObject {
 
 }
 
+/// A class that represents an emit that will request an ack that has not yet been sent.
+/// Call `timingOut(after:callback:)` to complete the emit
+/// Example:
+/// ```swift
+/// socket.emitWithAck("myEvent").timingOut(after: 1) {data in
+///     ...
+/// }
+/// ```
 public final class OnAckCallback : NSObject {
     private let ackNumber: Int
     private let items: [Any]
@@ -67,6 +87,13 @@ public final class OnAckCallback : NSObject {
         DefaultSocketLogger.Logger.log("OnAckCallback for \(ackNumber) being released", type: "OnAckCallback")
     }
 
+    // MARK: Methods
+
+    /// Completes an emitWithAck. If this isn't called, the emit never happens.
+    ///
+    /// - parameter after: The number of seconds before this emit times out if an ack hasn't been received.
+    /// - parameter callback: The callback called when an ack is received, or when a timeout happens.
+    ///                       To check for timeout, use `SocketAckStatus`'s `noAck` case.
     public func timingOut(after seconds: Int, callback: @escaping AckCallback) {
         guard let socket = self.socket else { return }
 

Source/SocketAckManager.swift

@@ -25,7 +25,9 @@
 import Dispatch
 import Foundation
 
+/// The status of an ack.
 public enum SocketAckStatus : String {
+    /// The ack timed out.
     case noAck = "NO ACK"
 }