docs

SwiftDDP/DDPExtensions.swift

@@ -60,26 +60,73 @@ extension NSDictionary {
 // These are implemented as an extension because they're not a part of the DDP spec
 extension DDPClient {
     
+    /**
+    Sends a subscription request to the server.
+    
+    - parameter name:       The name of the subscription
+    */
     public func subscribe(name:String) -> String { return sub(name, params:nil) }
     
+    /**
+    Sends a subscription request to the server.
+    
+    - parameter name:       The name of the subscription
+    - parameter params:     An object containing method arguments, if any
+    */
+    
     public func subscribe(name:String, params:[AnyObject]) -> String { return sub(name, params:params) }
     
-    public func subscribe(name:String, params:[AnyObject]?, callback: (()->())?) -> String { return sub(name, params:params, callback:callback) }
+    /**
+    Sends a subscription request to the server. If a callback is passed, the callback asynchronously
+    runs when the client receives a 'ready' message indicating that the initial subset of documents contained
+    in the subscription has been sent by the server.
     
-    public func subscribe(name:String, callback: (()->())?) -> String { return sub(name, params:nil, callback:callback) }
+    - parameter name:       The name of the subscription
+    - parameter params:     An object containing method arguments, if any
+    - parameter callback:   The closure to be executed when the server sends a 'ready' message
+    */
+    public func subscribe(name:String, params:[AnyObject]?, callback: DDPCallback?) -> String { return sub(name, params:params, callback:callback) }
     
-    // callback is optional. If present, called with an error object as the first argument and,
-    // if no error, the _id as the second.
-    public func insert(collection: String, document: NSArray, callback: ((result:AnyObject?, error:DDPError?) -> ())?) -> String {
+    /**
+    Sends a subscription request to the server. If a callback is passed, the callback asynchronously
+    runs when the client receives a 'ready' message indicating that the initial subset of documents contained
+    in the subscription has been sent by the server.
+    
+    - parameter name:       The name of the subscription
+    - parameter callback:   The closure to be executed when the server sends a 'ready' message
+    */
+    public func subscribe(name:String, callback: DDPCallback?) -> String { return sub(name, params:nil, callback:callback) }
+    
+    
+    /**
+    Asynchronously inserts a document into a collection on the server
+    
+    - parameter collection: The name of the collection
+    - parameter document:   An NSArray of documents to insert
+    - parameter callback:   A closure with result and error arguments describing the result of the operation
+    */
+    public func insert(collection: String, document: NSArray, callback: DDPMethodCallback?) -> String {
         let arg = "/\(collection)/insert"
         return self.method(arg, params: document, callback: callback)
     }
     
-    // Insert without specifying a callback
+    /**
+    Asynchronously inserts a document into a collection on the server
+    
+    - parameter collection: The name of the collection
+    - parameter document:   An NSArray of documents to insert
+    */
+    
     public func insert(collection: String, document: NSArray) -> String {
         return insert(collection, document: document, callback:nil)
     }
     
+    /**
+    Synchronously inserts a document into a collection on the server. Cannot be used on the main queue.
+    
+    - parameter collection: The name of the collection
+    - parameter document:   An NSArray of documents to insert
+    */
     public func insert(sync collection: String, document: NSArray) -> Result {
         
         syncWarning("Insert")
@@ -98,16 +145,34 @@ extension DDPClient {
         return serverResponse
     }
     
-    public func update(collection: String, document: NSArray, callback: ((result:AnyObject?, error:DDPError?) -> ())?) -> String {
+    /**
+    Asynchronously updates a document into a collection on the server
+    
+    - parameter collection: The name of the collection
+    - parameter document:   An NSArray of documents to update
+    - parameter callback:   A closure with result and error arguments describing the result of the operation
+    */
+    public func update(collection: String, document: NSArray, callback: DDPMethodCallback?) -> String {
         let arg = "/\(collection)/update"
         return method(arg, params: document, callback: callback)
     }
     
-    // Update without specifying a callback
+    /**
+    Asynchronously updates a document on the server
+    
+    - parameter collection: The name of the collection
+    - parameter document:   An NSArray of documents to update
+    */
     public func update(collection: String, document: NSArray) -> String {
         return update(collection, document: document, callback:nil)
     }
     
+    /**
+    Synchronously updates a document on the server. Cannot be used on the main queue
+    
+    - parameter collection: The name of the collection
+    - parameter document:   An NSArray of documents to update
+    */
     public func update(sync collection: String, document: NSArray) -> Result {
         syncWarning("Update")
         
@@ -125,16 +190,34 @@ extension DDPClient {
         return serverResponse
     }
     
-    public func remove(collection: String, document: NSArray, callback: ((result:AnyObject?, error:DDPError?) -> ())?) -> String {
+    /**
+    Asynchronously removes a document on the server
+    
+    - parameter collection: The name of the collection
+    - parameter document:   An NSArray of documents to remove
+    - parameter callback:   A closure with result and error arguments describing the result of the operation
+    */
+    public func remove(collection: String, document: NSArray, callback: DDPMethodCallback?) -> String {
         let arg = "/\(collection)/remove"
         return method(arg, params: document, callback: callback)
     }
     
-    // Remove without specifying a callback
+    /**
+    Asynchronously removes a document into a collection on the server
+    
+    - parameter collection: The name of the collection
+    - parameter document:   An NSArray of documents to remove
+    */
     public func remove(collection: String, document: NSArray) -> String  {
         return remove(collection, document: document, callback:nil)
     }
     
+    /**
+    Synchronously removes a document into a collection on the server. Cannot be used on the main queue.
+    
+    - parameter collection: The name of the collection
+    - parameter document:   An NSArray of documents to remove
+    */
     public func remove(sync collection: String, document: NSArray) -> Result {
         syncWarning("Remove")
         
@@ -181,17 +264,27 @@ extension DDPClient {
             if let c = callback { c(result: result, error: error) }
         }
     }
+
+    /**
+    Logs a user into the server using an email and password
     
-    // Login with email and password
-    public func loginWithPassword(email: String, password: String, callback: ((result:AnyObject?, error:DDPError?) -> ())?) {
+    - parameter email:      An email string
+    - parameter password:   A password string
+    - parameter callback:   A closure with result and error parameters describing the outcome of the operation
+    */
+    public func loginWithPassword(email: String, password: String, callback: DDPMethodCallback?) {
         if !(loginWithToken(callback)) {
             let params = ["user": ["email": email], "password":["digest": password.sha256()!, "algorithm":"sha-256"]] as NSDictionary
             login(params, callback: callback)
         }
     }
     
-    // Does the date comparison account for TimeZone?
-    public func loginWithToken(callback:((result: AnyObject?, error: DDPError?) -> ())?) -> Bool {
+    /**
+    Attempts to login a user with a token, if one exists
+    
+    - parameter callback:   A closure with result and error parameters describing the outcome of the operation
+    */
+    public func loginWithToken(callback: DDPMethodCallback?) -> Bool {
         if let token = userData.stringForKey(DDP_TOKEN),
             let tokenDate = userData.objectForKey(DDP_TOKEN_EXPIRES) {
                 if (tokenDate.compare(NSDate()) == NSComparisonResult.OrderedDescending) {
@@ -203,6 +296,7 @@ extension DDPClient {
         return false
     }
     
+    
     public func signup(params:NSDictionary, callback:((result: AnyObject?, error: DDPError?) -> ())?) {
         method("createUser", params: NSArray(arrayLiteral: params)) { result, error in
             guard let e = error where (e.isValid == true) else {
@@ -255,17 +349,33 @@ extension DDPClient {
         }
     }
     
-    public func logout(callback: ((result: AnyObject?, error: DDPError?) -> ())?) {
+    /**
+    Logs a user out and removes their account data from NSUserDefaults
+    
+    - parameter callback:   A closure with result and error parameters describing the outcome of the operation
+    */
+    public func logout(callback:DDPMethodCallback?) {
         method("logout", params: nil, callback: callback)
     }
     
-    public convenience init(url: String, email: String, password: String, callback: (result:AnyObject?, error:DDPError?) -> ()) {
+    /**
+    Connects and logs in with an email address and password in one action
+    
+    - parameter url:        String url, ex. wss://todos.meteor.com/websocket
+    - parameter email:      String email address
+    - parameter password:   String password
+    - parameter callback:   A closure with result and error parameters describing the outcome of the operation
+    */
+    public convenience init(url: String, email: String, password: String, callback: DDPMethodCallback?) {
         self.init()
         connect(url) { session in
             self.loginWithPassword(email, password: password, callback:callback)
         }
     }
     
+    /**
+    Returns true if the user is logged in, and false otherwise
+    */
     public func loggedIn() -> Bool {
         if let userLoggedIn = self.userData.objectForKey(DDP_LOGGED_IN) as? Bool where (userLoggedIn == true) {
             return true