     private var retries = 0
     private var maxRetries = 2
 
+    /// A function executed whenever text is received from the remote server.
     var onText: (String -> Void)?
+
+    /// A function executed whenever data is received from the remote server.
     var onData: (NSData -> Void)?
+
+    /// A function executed whenever an error is produced by the WebSockets connection.
     var onError: (NSError -> Void)?
 
+    /**
+     Create a `WatsonWebSocket`
+    
+     - parameter authStrategy: An `AuthenticationStrategy` that defines how to authenticate
+        with a Watson Developer Cloud service. The `AuthenticationStrategy` is used internally
+        to obtain tokens, refresh expired tokens, and maintain information about authentication
+        state.
+     - parameter url: The url of the remote server.
+     - parameter protocols: The WebSockets protocols that should be used for this connection.
+    
+     - returns: A `WatsonWebSocket` that can be used to send text and data to the remote server.
+     */
     init(authStrategy: AuthenticationStrategy, url: NSURL, protocols: [String]? = nil) {
         self.authStrategy = authStrategy
 

            self.operations.suspended = true
            self.isConnecting = false
            if self.isAuthenticationFailure(error) {
                self.retries += 1
                self.connectWithToken()
            } else if let error = error {
                self.isClosedByError = true

import Foundation
import Starscream

/**
 Abstracts a WebSockets connection. In particular, `WatsonWebSocket` internally manages the state
 of the connection and queues any operations requested while the socket is disconnected.
 */
class WatsonWebSocket {

    private let authStrategy: AuthenticationStrategy
