docs: improve documentation sections (#276)

* docs: improve ParseUser documentation * more docs * fixes * conform to protocol * More doc updates * bump version * Remove codecov filter * nits
parse-community · Nov 8, 2021 · 7c6c305 · 7c6c305
1 parent 37a2247
commit 7c6c305
Show file tree

Hide file tree

Showing 38 changed files with 133 additions and 81 deletions.
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -25,7 +25,6 @@ jobs:
       uses: sersoft-gmbh/swift-coverage-action@v2
       id: coverage-files
       with:
-        target-name-filter: '^ParseSwift$'
         format: lcov
         search-paths: ./DerivedData
       env:

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -2,9 +2,15 @@
 
 ### main
 
-[Full Changelog](https://github.com/parse-community/Parse-Swift/compare/2.2.2...main)
+[Full Changelog](https://github.com/parse-community/Parse-Swift/compare/2.2.3...main)
 * _Contributing to this repo? Add info about your change here to be included in the next release_
 
+### 2.2.3
+[Full Changelog](https://github.com/parse-community/Parse-Swift/compare/2.2.2...2.2.3)
+
+__Fixes__
+- Improve dpcumentation ([#276](https://github.com/parse-community/Parse-Swift/pull/276)), thanks to [Corey Baker](https://github.com/cbaker6).
+
 ### 2.2.2
 [Full Changelog](https://github.com/parse-community/Parse-Swift/compare/2.2.1...2.2.2)
 

diff --git a/ParseSwift.playground/Pages/13 - Operations.xcplaygroundpage/Contents.swift b/ParseSwift.playground/Pages/13 - Operations.xcplaygroundpage/Contents.swift
@@ -21,7 +21,7 @@ struct GameScore: ParseObject {
     var ACL: ParseACL?
 
     //: Your own properties.
-    var score: Int = 0
+    var score: Int? = 0
 }
 
 //: It's recommended to place custom initializers in an extension
@@ -45,7 +45,7 @@ do {
     savedScore = try GameScore(score: 102).save()
 } catch {
     savedScore = nil
-    fatalError("Error saving: \(error)")
+    assertionFailure("Error saving: \(error)")
 }
 
 //: Then we will increment the score.
@@ -69,8 +69,20 @@ do {
     print(error)
 }
 
-//: There are other operations: add/remove/delete objects from `ParseObject`s.
+//: You can also remove a value for a property using unset.
+let unsetOperation = savedScore
+    .operation.unset(("score", \.score))
+do {
+    let updatedScore = try unsetOperation.save()
+    print("Updated score: \(updatedScore). Check the new score on Parse Dashboard.")
+} catch {
+    print(error)
+}
+
+//: There are other operations: set/forceSet/unset/add/remove, etc. objects from `ParseObject`s.
 //: In fact, the `users` and `roles` relations from `ParseRoles` used the add/remove operations.
+//: Multiple operations can be chained together. See:
+//: https://github.com/parse-community/Parse-Swift/pull/268#issuecomment-955714414
 let operations = savedScore.operation
 
 //: Example: operations.add("hello", objects: ["test"]).

diff --git a/Sources/ParseSwift/Authentication/3rd Party/ParseApple/ParseApple+async.swift b/Sources/ParseSwift/Authentication/3rd Party/ParseApple/ParseApple+async.swift
@@ -11,7 +11,7 @@ import Foundation
 
 @available(macOS 12.0, iOS 15.0, watchOS 8.0, tvOS 15.0, *)
 public extension ParseApple {
-    // MARK: Login - Async/Await
+    // MARK: Async/Await
 
     /**
      Login a `ParseUser` *asynchronously* using Apple authentication.
@@ -51,7 +51,6 @@ public extension ParseApple {
 
 @available(macOS 12.0, iOS 15.0, watchOS 8.0, tvOS 15.0, *)
 public extension ParseApple {
-    // MARK: Link - Async/Await
 
     /**
      Link the *current* `ParseUser` *asynchronously* using Apple authentication.

diff --git a/Sources/ParseSwift/Authentication/3rd Party/ParseApple/ParseApple+combine.swift b/Sources/ParseSwift/Authentication/3rd Party/ParseApple/ParseApple+combine.swift
@@ -11,7 +11,7 @@ import Foundation
 import Combine
 
 public extension ParseApple {
-    // MARK: Login - Combine
+    // MARK: Combine
 
     /**
      Login a `ParseUser` *asynchronously* using Apple authentication. Publishes when complete.
@@ -48,7 +48,6 @@ public extension ParseApple {
 }
 
 public extension ParseApple {
-    // MARK: Link - Combine
 
     /**
      Link the *current* `ParseUser` *asynchronously* using Apple authentication. Publishes when complete.

diff --git a/Sources/ParseSwift/Authentication/3rd Party/ParseFacebook/ParseFacebook+async.swift b/Sources/ParseSwift/Authentication/3rd Party/ParseFacebook/ParseFacebook+async.swift
@@ -11,7 +11,7 @@ import Foundation
 
 @available(macOS 12.0, iOS 15.0, watchOS 8.0, tvOS 15.0, *)
 public extension ParseFacebook {
-    // MARK: Login - Async/Await
+    // MARK: Async/Await
 
     /**
      Login a `ParseUser` *asynchronously* using Facebook authentication for limited login.
@@ -75,7 +75,6 @@ public extension ParseFacebook {
 
 @available(macOS 12.0, iOS 15.0, watchOS 8.0, tvOS 15.0, *)
 public extension ParseFacebook {
-    // MARK: Link - Async/Await
     /**
      Link the *current* `ParseUser` *asynchronously* using Facebook authentication for limited login.
      - parameter userId: The `userId` from `FacebookSDK`.

diff --git a/Sources/ParseSwift/Authentication/3rd Party/ParseFacebook/ParseFacebook+combine.swift b/Sources/ParseSwift/Authentication/3rd Party/ParseFacebook/ParseFacebook+combine.swift
@@ -11,7 +11,7 @@ import Foundation
 import Combine
 
 public extension ParseFacebook {
-    // MARK: Login - Combine
+    // MARK: Combine
     /**
      Login a `ParseUser` *asynchronously* using Facebook authentication for limited login. Publishes when complete.
      - parameter userId: The `userId` from `FacebookSDK`.
@@ -70,7 +70,6 @@ public extension ParseFacebook {
 }
 
 public extension ParseFacebook {
-    // MARK: Link - Combine
     /**
      Link the *current* `ParseUser` *asynchronously* using Facebook authentication for limited login.
      Publishes when complete.

diff --git a/Sources/ParseSwift/Authentication/3rd Party/ParseLDAP/ParseLDAP+async.swift b/Sources/ParseSwift/Authentication/3rd Party/ParseLDAP/ParseLDAP+async.swift
@@ -11,7 +11,7 @@ import Foundation
 
 @available(macOS 12.0, iOS 15.0, watchOS 8.0, tvOS 15.0, *)
 public extension ParseLDAP {
-    // MARK: Login - Async/Await
+    // MARK: Async/Await
     /**
      Login a `ParseUser` *asynchronously* using LDAP authentication.
      - parameter id: The id of the `user`.
@@ -50,7 +50,6 @@ public extension ParseLDAP {
 
 @available(macOS 12.0, iOS 15.0, watchOS 8.0, tvOS 15.0, *)
 public extension ParseLDAP {
-    // MARK: Link - Async/Await
     /**
      Link the *current* `ParseUser` *asynchronously* using LDAP authentication.
      - parameter id: The id of the `user`.

diff --git a/Sources/ParseSwift/Authentication/3rd Party/ParseLDAP/ParseLDAP+combine.swift b/Sources/ParseSwift/Authentication/3rd Party/ParseLDAP/ParseLDAP+combine.swift
@@ -11,7 +11,7 @@ import Foundation
 import Combine
 
 public extension ParseLDAP {
-    // MARK: Login - Combine
+    // MARK: Combine
     /**
      Login a `ParseUser` *asynchronously* using LDAP authentication. Publishes when complete.
      - parameter id: The id of the `user`.
@@ -47,7 +47,6 @@ public extension ParseLDAP {
 }
 
 public extension ParseLDAP {
-    // MARK: Link - Combine
     /**
      Link the *current* `ParseUser` *asynchronously* using LDAP authentication. Publishes when complete.
      - parameter id: The id of the `user`.

diff --git a/Sources/ParseSwift/Authentication/3rd Party/ParseTwitter/ParseTwitter+async.swift b/Sources/ParseSwift/Authentication/3rd Party/ParseTwitter/ParseTwitter+async.swift
@@ -11,7 +11,7 @@ import Foundation
 
 @available(macOS 12.0, iOS 15.0, watchOS 8.0, tvOS 15.0, *)
 public extension ParseTwitter {
-    // MARK: Login - Async/Await
+    // MARK: Async/Await
 
     /**
      Login a `ParseUser` *asynchronously* using Twitter authentication.
@@ -63,7 +63,6 @@ public extension ParseTwitter {
 
 @available(macOS 12.0, iOS 15.0, watchOS 8.0, tvOS 15.0, *)
 public extension ParseTwitter {
-    // MARK: Link - Async/Await
 
     /**
      Link the *current* `ParseUser` *asynchronously* using Twitter authentication.

diff --git a/Sources/ParseSwift/Authentication/3rd Party/ParseTwitter/ParseTwitter+combine.swift b/Sources/ParseSwift/Authentication/3rd Party/ParseTwitter/ParseTwitter+combine.swift
@@ -11,7 +11,7 @@ import Foundation
 import Combine
 
 public extension ParseTwitter {
-    // MARK: Login - Combine
+    // MARK: Combine
 
     /**
      Login a `ParseUser` *asynchronously* using Twitter authentication. Publishes when complete.
@@ -60,7 +60,6 @@ public extension ParseTwitter {
 }
 
 public extension ParseTwitter {
-    // MARK: Link - Combine
 
     /**
      Link the *current* `ParseUser` *asynchronously* using Twitter authentication. Publishes when complete.

diff --git a/Sources/ParseSwift/Authentication/Internal/ParseAnonymous+async.swift b/Sources/ParseSwift/Authentication/Internal/ParseAnonymous+async.swift
@@ -12,11 +12,10 @@ import Foundation
 @available(macOS 12.0, iOS 15.0, watchOS 8.0, tvOS 15.0, *)
 public extension ParseAnonymous {
 
-    // MARK: Login - Async/Await
+    // MARK: Async/Await
     /**
      Login a `ParseUser` *asynchronously* using the respective authentication type.
      - parameter options: A set of header options sent to the server. Defaults to an empty set.
-     - parameter callbackQueue: The queue to return to after completion. Default value of .main.
      - returns: An instance of the logged in `ParseUser`.
      - throws: `ParseError`.
      */
@@ -31,7 +30,6 @@ public extension ParseAnonymous {
      Login a `ParseUser` *asynchronously* using the respective authentication type.
      - parameter authData: The authData for the respective authentication type. This will be ignored.
      - parameter options: A set of header options sent to the server. Defaults to an empty set.
-     - parameter callbackQueue: The queue to return to after completion. Default value of .main.
      - returns: An instance of the logged in `ParseUser`.
      - throws: `ParseError`.
      */
@@ -48,7 +46,6 @@ public extension ParseAnonymous {
 @available(macOS 12.0, iOS 15.0, watchOS 8.0, tvOS 15.0, *)
 public extension ParseAnonymous {
 
-    // MARK: Link - Async/Await
     func link(authData: [String: String],
               options: API.Options = []) async throws -> AuthenticatedUser {
         try await withCheckedThrowingContinuation { continuation in

diff --git a/Sources/ParseSwift/Authentication/Internal/ParseAnonymous+combine.swift b/Sources/ParseSwift/Authentication/Internal/ParseAnonymous+combine.swift
@@ -45,7 +45,6 @@ public extension ParseAnonymous {
 
 public extension ParseAnonymous {
 
-    // MARK: Link - Combine
     func linkPublisher(authData: [String: String],
                        options: API.Options = []) -> Future<AuthenticatedUser, ParseError> {
         Future { promise in

diff --git a/Sources/ParseSwift/Authentication/Internal/ParseAnonymous.swift b/Sources/ParseSwift/Authentication/Internal/ParseAnonymous.swift
@@ -65,7 +65,7 @@ public extension ParseAnonymous {
     func login(authData: [String: String],
                options: API.Options = []) throws -> AuthenticatedUser {
         try AuthenticatedUser.login(__type,
-                                    authData: AuthenticationKeys.id.makeDictionary(),
+                                    authData: authData,
                                     options: options)
     }
 
@@ -96,7 +96,7 @@ public extension ParseAnonymous {
                callbackQueue: DispatchQueue = .main,
                completion: @escaping (Result<AuthenticatedUser, ParseError>) -> Void) {
         AuthenticatedUser.login(__type,
-                                authData: AuthenticationKeys.id.makeDictionary(),
+                                authData: authData,
                                 options: options,
                                 callbackQueue: callbackQueue,
                                 completion: completion)

diff --git a/Sources/ParseSwift/Authentication/Protocols/ParseAuthentication+combine.swift b/Sources/ParseSwift/Authentication/Protocols/ParseAuthentication+combine.swift
@@ -90,7 +90,6 @@ public extension ParseUser {
                       completion: promise)
         }
     }
-
 }
 
 #endif
diff --git a/Sources/ParseSwift/Authentication/Protocols/ParseAuthentication.swift b/Sources/ParseSwift/Authentication/Protocols/ParseAuthentication.swift
@@ -96,8 +96,9 @@ public protocol ParseAuthentication: Codable {
     func strip(_ user: AuthenticatedUser) -> AuthenticatedUser
 
     #if canImport(Combine)
+    // MARK: Combine
     /**
-     Login a `ParseUser` *asynchronously* using the respective authentication type.
+     Login a `ParseUser` *asynchronously* using the respective authentication type. Publishes when complete.
      - parameter authData: The authData for the respective authentication type.
      - parameter options: A set of header options sent to the server. Defaults to an empty set.
      - parameter callbackQueue: The queue to return to after completion. Default value of .main.
@@ -107,7 +108,7 @@ public protocol ParseAuthentication: Codable {
                         options: API.Options) -> Future<AuthenticatedUser, ParseError>
 
     /**
-     Link the *current* `ParseUser` *asynchronously* using the respective authentication type.
+     Link the *current* `ParseUser` *asynchronously* using the respective authentication type. Publishes when complete.
      - parameter authData: The authData for the respective authentication type.
      - parameter options: A set of header options sent to the server. Defaults to an empty set.
      - parameter callbackQueue: The queue to return to after completion. Default value of .main.
@@ -117,7 +118,7 @@ public protocol ParseAuthentication: Codable {
                        options: API.Options) -> Future<AuthenticatedUser, ParseError>
 
     /**
-     Unlink the `ParseUser` *asynchronously* from the respective authentication type.
+     Unlink the `ParseUser` *asynchronously* from the respective authentication type. Publishes when complete.
      - parameter user: The `ParseUser` to unlink. The user must be logged in on this device.
      - parameter options: A set of header options sent to the server. Defaults to an empty set.
      - parameter callbackQueue: The queue to return to after completion. Default value of .main.
@@ -127,14 +128,45 @@ public protocol ParseAuthentication: Codable {
     func unlinkPublisher(_ user: AuthenticatedUser,
                          options: API.Options) -> Future<AuthenticatedUser, ParseError>
 
+    /**
+     Unlink the *current* `ParseUser` *asynchronously* from the respective authentication type. Publishes when complete.
+     - parameter options: A set of header options sent to the server. Defaults to an empty set.
+     - returns: A publisher that eventually produces a single value and then finishes or fails.
+     */
+    func unlinkPublisher(options: API.Options) -> Future<AuthenticatedUser, ParseError>
+    #endif
+
+    #if swift(>=5.5) && canImport(_Concurrency)
+    // MARK: Async/Await
+
+    /**
+     Link the *current* `ParseUser` *asynchronously* using the respective authentication type.
+     - parameter authData: The authData for the respective authentication type.
+     - parameter options: A set of header options sent to the server. Defaults to an empty set.
+     - parameter returns: An instance of the linked `AuthenticatedUser`.
+     */
+    @available(macOS 12.0, iOS 15.0, watchOS 8.0, tvOS 15.0, *)
+    func link(authData: [String: String],
+              options: API.Options) async throws -> AuthenticatedUser
+
+    /**
+     Unlink the `ParseUser` *asynchronously* from the respective authentication type.
+     - parameter user: The `ParseUser` to unlink. The user must be logged in on this device.
+     - parameter options: A set of header options sent to the server. Defaults to an empty set.
+     - parameter returns: An instance of the unlinked `AuthenticatedUser`.
+     */
+    @available(macOS 12.0, iOS 15.0, watchOS 8.0, tvOS 15.0, *)
+    func unlink(_ user: AuthenticatedUser,
+                options: API.Options) async throws -> AuthenticatedUser
+
     /**
      Unlink the *current* `ParseUser` *asynchronously* from the respective authentication type.
      - parameter options: A set of header options sent to the server. Defaults to an empty set.
      - parameter callbackQueue: The queue to return to after completion. Default value of .main.
-     - parameter completion: The block to execute.
-     It should have the following argument signature: `(Result<Self, ParseError>)`.
+     - parameter returns: An instance of the unlinked `AuthenticatedUser`.
      */
-    func unlinkPublisher(options: API.Options) -> Future<AuthenticatedUser, ParseError>
+    @available(macOS 12.0, iOS 15.0, watchOS 8.0, tvOS 15.0, *)
+    func unlink(options: API.Options) async throws -> AuthenticatedUser
     #endif
 }
 

diff --git a/Sources/ParseSwift/Objects/ParseInstallation+async.swift b/Sources/ParseSwift/Objects/ParseInstallation+async.swift
@@ -12,7 +12,7 @@ import Foundation
 @available(macOS 12.0, iOS 15.0, watchOS 8.0, tvOS 15.0, *)
 public extension ParseInstallation {
 
-    // MARK: Fetchable - Async/Await
+    // MARK: Async/Await
     /**
      Fetches the `ParseInstallation` *aynchronously* with the current data from the server
      and sets an error if one occurs. Publishes when complete.
@@ -35,7 +35,6 @@ public extension ParseInstallation {
         }
     }
 
-    // MARK: Savable - Async/Await
     /**
      Saves the `ParseInstallation` *asynchronously*.
      - parameter isIgnoreCustomObjectIdConfig: Ignore checking for `objectId`
@@ -55,7 +54,6 @@ public extension ParseInstallation {
         }
     }
 
-    // MARK: Deletable - Async/Await
     /**
      Deletes the `ParseInstallation` *asynchronously*.
 
@@ -71,7 +69,6 @@ public extension ParseInstallation {
     }
 }
 
-// MARK: Batch Support - Async/Await
 @available(macOS 12.0, iOS 15.0, watchOS 8.0, tvOS 15.0, *)
 public extension Sequence where Element: ParseInstallation {
     /**

diff --git a/Sources/ParseSwift/Objects/ParseInstallation+combine.swift b/Sources/ParseSwift/Objects/ParseInstallation+combine.swift
@@ -64,7 +64,6 @@ public extension ParseInstallation {
     }
 }
 
-// MARK: Batch Support - Combine
 public extension Sequence where Element: ParseInstallation {
     /**
      Fetches a collection of installations *aynchronously* with the current data from the server and sets

diff --git a/Sources/ParseSwift/Objects/ParseObject+async.swift b/Sources/ParseSwift/Objects/ParseObject+async.swift
@@ -70,7 +70,6 @@ public extension ParseObject {
 
 @available(macOS 12.0, iOS 15.0, watchOS 8.0, tvOS 15.0, *)
 public extension Sequence where Element: ParseObject {
-    // MARK: Batch Support - Async/Await
     /**
      Fetches a collection of objects *aynchronously* with the current data from the server and sets
      an error if one occurs.

diff --git a/Sources/ParseSwift/Objects/ParseObject+combine.swift b/Sources/ParseSwift/Objects/ParseObject+combine.swift
@@ -64,7 +64,6 @@ public extension ParseObject {
 }
 
 public extension Sequence where Element: ParseObject {
-    // MARK: Batch Support - Combine
     /**
      Fetches a collection of objects *aynchronously* with the current data from the server and sets
      an error if one occurs. Publishes when complete.