FirebaseCombineSwift: Docs & API cleanup (#8088)

* Docs & API cleanup

* Style

* Review

* Review 2

* Review 3

* Review 4

* Review 5

Author: ncooke3

FirebaseCombineSwift/Sources/Auth/Auth+Combine.swift

@@ -18,7 +18,7 @@
   import FirebaseAuth
 
   @available(swift 5.0)
-  @available(macOS 10.15, iOS 13, watchOS 6, tvOS 13, *)
+  @available(iOS 13.0, macOS 10.15, macCatalyst 13.0, tvOS 13.0, watchOS 6.0, *)
   extension Auth {
     // MARK: - Authentication State Management
 
@@ -27,12 +27,13 @@
     /// The publisher emits values when:
     ///
     /// - It is registered,
-    /// - A user with a different UID from the current user has signed in, or
-    /// - The current user has signed out.
+    /// - a user with a different UID from the current user has signed in, or
+    /// - the current user has signed out.
     ///
     /// The publisher will emit events on the **main** thread.
     ///
-    /// - Returns: A publisher emitting a `User` instance (if the user has signed in) or `nil` (if the user has signed out)
+    /// - Returns: A publisher emitting a `User` instance (if the user has signed in) or `nil` (if the user has signed out).
+    /// The publisher will emit on the *main* thread.
     public func authStateDidChangePublisher() -> AnyPublisher<User?, Never> {
       let subject = PassthroughSubject<User?, Never>()
       let handle = addStateDidChangeListener { auth, user in
@@ -50,14 +51,15 @@
     /// The publisher emits values when:
     ///
     /// - It is registered,
-    /// - A user with a different UID from the current user has signed in,
-    /// - The ID token of the current user has been refreshed, or
-    /// - The current user has signed out.
+    /// - a user with a different UID from the current user has signed in,
+    /// - the ID token of the current user has been refreshed, or
+    /// - the current user has signed out.
     ///
     /// The publisher will emit events on the **main** thread.
     ///
-    /// - Returns: A publisher emitting a `User` instance (if a different user as signed in or
-    ///   the ID token of the current user has changed) or `nil` (if the user has signed out)
+    /// - Returns: A publisher emitting a `User` instance (if a different user is signed in or
+    ///   the ID token of the current user has changed) or `nil` (if the user has signed out).
+    ///   The publisher will emit on the *main* thread.
     public func idTokenDidChangePublisher() -> AnyPublisher<User?, Never> {
       let subject = PassthroughSubject<User?, Never>()
       let handle = addIDTokenDidChangeListener { auth, user in
@@ -70,13 +72,13 @@
         .eraseToAnyPublisher()
     }
 
-    /// Sets the currentUser on the calling Auth instance to the provided user object.
+    /// Sets the `currentUser` on the calling Auth instance to the provided `user` object.
     ///
     /// The publisher will emit events on the **main** thread.
     ///
     /// - Parameter user: The user object to be set as the current user of the calling Auth instance.
-    /// - Returns: A publisher that emits as soon as the user of the calling Auth instance has been
-    ///   updated or an error was encountered. The publisher will emit on the *main* thread.
+    /// - Returns: A publisher that emits when the user of the calling Auth instance has been updated or
+    /// an error was encountered. The publisher will emit on the **main** thread.
     @discardableResult
     public func updateCurrentUser(_ user: User) -> Future<Void, Error> {
       Future<Void, Error> { promise in
@@ -92,14 +94,14 @@
 
     // MARK: - Anonymous Authentication
 
-    /// Asynchronously creates and becomes an anonymous user.
+    /// Asynchronously creates an anonymous user and assigns it as the calling Auth instance's current user.
     ///
     /// If there is already an anonymous user signed in, that user will be returned instead.
     /// If there is any other existing user signed in, that user will be signed out.
     ///
     /// The publisher will emit events on the **main** thread.
     ///
-    /// - Returns: A publisher that emits the result of the sign in flow.
+    /// - Returns: A publisher that emits the result of the sign in flow. The publisher will emit on the *main* thread.
     /// - Remark:
     ///   Possible error codes:
     ///   - `AuthErrorCodeOperationNotAllowed` - Indicates that anonymous accounts are
@@ -128,7 +130,7 @@
     /// - Parameters:
     ///   - email: The user's email address.
     ///   - password: The user's desired password.
-    /// - Returns: A publisher that emits the result of the sign in flow.
+    /// - Returns: A publisher that emits the result of the sign in flow. The publisher will emit on the *main* thread.
     /// - Remark:
     ///   Possible error codes:
     ///   - `AuthErrorCodeInvalidEmail` - Indicates the email address is malformed.
@@ -156,14 +158,14 @@
       }
     }
 
-    /// Signs in using an email address and password.
+    /// Signs in a user with the given email address and password.
     ///
     /// The publisher will emit events on the **main** thread.
     ///
     /// - Parameters:
     ///   - email: The user's email address.
-    ///   - password: The user's desired password.
-    /// - Returns: A publisher that emits the result of the sign in flow.
+    ///   - password: The user's password.
+    /// - Returns: A publisher that emits the result of the sign in flow. The publisher will emit on the *main* thread.
     /// - Remark:
     ///   Possible error codes:
     ///   - `AuthErrorCodeOperationNotAllowed` - Indicates that email and password
@@ -198,7 +200,7 @@
     /// - Parameters:
     ///   - email: The user's email address.
     ///   - link: The email sign-in link.
-    /// - Returns: A publisher that emits the result of the sign in flow.
+    /// - Returns: A publisher that emits the result of the sign in flow. The publisher will emit on the *main* thread.
     /// - Remark:
     ///   Possible error codes:
     ///   - `AuthErrorCodeOperationNotAllowed` - Indicates that email and password
@@ -208,6 +210,7 @@
     ///   - `AuthErrorCodeInvalidEmail` - Indicates the email address is malformed.
     ///
     ///   See `AuthErrors` for a list of error codes that are common to all API methods
+    @available(watchOS, unavailable)
     @discardableResult
     public func signIn(withEmail email: String,
                        link: String) -> Future<AuthDataResult, Error> {
@@ -230,7 +233,8 @@
     ///   - email: The email address of the user.
     ///   - actionCodeSettings: An `ActionCodeSettings` object containing settings related to
     ///     handling action codes.
-    /// - Returns: A publisher that emits whether the call was successful or not.
+    /// - Returns: A publisher that emits whether the call was successful or not. The publisher will emit on the *main* thread.
+    @available(watchOS, unavailable)
     @discardableResult
     public func sendSignInLink(toEmail email: String,
                                actionCodeSettings: ActionCodeSettings) -> Future<Void, Error> {
@@ -253,7 +257,7 @@
     ///
     /// - Parameter email: The email address for which to obtain a list of sign-in methods.
     /// - Returns: A publisher that emits a list of sign-in methods for the specified email
-    ///   address, or an error if one occurred.
+    ///   address, or an error if one occurred. The publisher will emit on the *main* thread.
     /// - Remark: Possible error codes:
     ///   - `AuthErrorCodeInvalidEmail` - Indicates the email address is malformed.
     ///
@@ -277,12 +281,12 @@
     /// The publisher will emit events on the **main** thread.
     ///
     /// - Parameters:
-    ///   - code: Out-of-band code given to the user outside of the app.
+    ///   - code: Out-of-band (OOB) code given to the user outside of the app.
     ///   - newPassword: The new password.
-    /// - Returns: A publisher that emits whether the call was successful or not.
+    /// - Returns: A publisher that emits whether the call was successful or not. The publisher will emit on the *main* thread.
     /// - Remark: Possible error codes:
     ///   - `AuthErrorCodeWeakPassword` - Indicates an attempt to set a password that is considered too weak.
-    ///   - `AuthErrorCodeOperationNotAllowed` - Indicates the administrator disabled sign in with the specified identity provider.
+    ///   - `AuthErrorCodeOperationNotAllowed` - Indicates the admin disabled sign in with the specified identity provider.
     ///   - `AuthErrorCodeExpiredActionCode` - Indicates the OOB code is expired.
     ///   - `AuthErrorCodeInvalidActionCode` - Indicates the OOB code is invalid.
     ///
@@ -308,6 +312,7 @@
     /// - Parameter code: The password reset code to be verified.
     /// - Returns: A publisher that emits an error if the code could not be verified. If the code could be
     ///   verified, the publisher will emit the email address of the account the code was issued for.
+    ///   The publisher will emit on the *main* thread.
     @discardableResult
     public func verifyPasswordResetCode(_ code: String) -> Future<String, Error> {
       Future<String, Error> { promise in
@@ -326,8 +331,8 @@
     /// The publisher will emit events on the **main** thread.
     ///
     /// - Parameter code: The out of band code to check validity.
-    /// - Returns: A publisher that emits an error if the code could not be verified. If the code could be
-    ///   verified, the publisher will emit the email address of the account the code was issued for.
+    /// - Returns: A publisher that emits the email address of the account the code was issued for or an error if
+    ///   the code could not be verified. The publisher will emit on the *main* thread.
     @discardableResult
     public func checkActionCode(code: String) -> Future<ActionCodeInfo, Error> {
       Future<ActionCodeInfo, Error> { promise in
@@ -345,10 +350,10 @@
     ///
     /// The publisher will emit events on the **main** thread.
     ///
-    /// - Parameter code: The out of band code to be applied.
-    /// - Returns: A publisher that emits an error if the code could not be applied.
-    /// - Remark: This method will not work for out of band codes which require an additional parameter,
-    ///   such as password reset code.
+    /// - Parameter code: The out-of-band (OOB) code to be applied.
+    /// - Returns: A publisher that emits an error if the code could not be applied. The publisher will emit on the *main* thread.
+    /// - Remark: This method will not work for out-of-band codes which require an additional parameter,
+    ///   such as password reset codes.
     @discardableResult
     public func applyActionCode(code: String) -> Future<Void, Error> {
       Future<Void, Error> { promise in
@@ -367,7 +372,7 @@
     /// The publisher will emit events on the **main** thread.
     ///
     /// - Parameter email: The email address of the user.
-    /// - Returns: A publisher that emits whether the call was successful or not.
+    /// - Returns: A publisher that emits whether the call was successful or not. The publisher will emit on the *main* thread.
     /// - Remark: Possible error codes:
     ///   - `AuthErrorCodeInvalidRecipientEmail` - Indicates an invalid recipient email was sent in the request.
     ///   - `AuthErrorCodeInvalidSender` - Indicates an invalid sender email is set in the console for this action.
@@ -392,15 +397,19 @@
     /// The publisher will emit events on the **main** thread.
     ///
     /// - Parameter email: The email address of the user.
-    /// - Parameter actionCodeSettings: An `ActionCodeSettings` object containing settings related t handling action codes.
-    /// - Returns: A publisher that emits whether the call was successful or not.
+    /// - Parameter actionCodeSettings: An `ActionCodeSettings` object containing settings related to
+    /// handling action codes.
+    /// - Returns: A publisher that emits whether the call was successful or not. The publisher will emit on the *main* thread.
     /// - Remark: Possible error codes:
     ///   - `AuthErrorCodeInvalidRecipientEmail` - Indicates an invalid recipient email was sent in the request.
     ///   - `AuthErrorCodeInvalidSender` - Indicates an invalid sender email is set in the console for this action.
     ///   - `AuthErrorCodeInvalidMessagePayload` - Indicates an invalid email template for sending update email.
-    ///   - `AuthErrorCodeMissingIosBundleID` - Indicates that the iOS bundle ID is missing when `handleCodeInApp` is set to YES.
-    ///   - `AuthErrorCodeMissingAndroidPackageName` - Indicates that the android package name is missing when the `androidInstallApp` flag is set to true.
-    ///   - `AuthErrorCodeUnauthorizedDomain` - Indicates that the domain specified in the continue URL is not whitelisted in the Firebase console.
+    ///   - `AuthErrorCodeMissingIosBundleID` - Indicates that the iOS bundle ID is missing
+    ///   when `handleCodeInApp` is set to YES.
+    ///   - `AuthErrorCodeMissingAndroidPackageName` - Indicates that the android package name is missing
+    ///   when the `androidInstallApp` flag is set to true.
+    ///   - `AuthErrorCodeUnauthorizedDomain` - Indicates that the domain specified in the continue URL is not whitelisted
+    ///    in the Firebase console.
     ///   - `AuthErrorCodeInvalidContinueURI` - Indicates that the domain specified in the continue URI is not valid.
     ///
     ///   See `AuthErrors` for a list of error codes that are common to all API methods
@@ -420,15 +429,14 @@
 
     // MARK: - Other Authentication providers
 
-    #if !os(tvOS) && !os(macOS)
-
+    #if os(iOS) || targetEnvironment(macCatalyst)
       /// Signs in using the provided auth provider instance.
       ///
       /// The publisher will emit events on the **main** thread.
       ///
       /// - Parameters:
       ///   - provider: An instance of an auth provider used to initiate the sign-in flow.
-      ///   - uiDelegate: Optionally an instance of a class conforming to the `AuthUIDelegate`
+      ///   - uiDelegate: Optionally, an instance of a class conforming to the `AuthUIDelegate`
       ///   protocol. This is used for presenting the web context. If `nil`, a default `AuthUIDelegate`
       ///   will be used.
       /// - Returns: A publisher that emits an `AuthDataResult` when the sign-in flow completed
@@ -466,8 +474,7 @@
           }
         }
       }
-
-    #endif
+    #endif // os(iOS) || targetEnvironment(macCatalyst)
 
     /// Asynchronously signs in to Firebase with the given Auth token.
     ///
@@ -545,4 +552,5 @@
       }
     }
   }
-#endif
+
+#endif // canImport(Combine) && swift(>=5.0) && canImport(FirebaseAuth)

FirebaseCombineSwift/Sources/Auth/GameCenterAuthProvider+Combine.swift

@@ -18,10 +18,10 @@
   import FirebaseAuth
 
   @available(swift 5.0)
+  @available(iOS 13.0, macOS 10.15, macCatalyst 13.0, tvOS 13.0, *)
   @available(watchOS, unavailable)
-  @available(macOS 10.15, iOS 13, tvOS 13, *)
   extension GameCenterAuthProvider {
-    /// Creates a `AuthCredential` for a Game Center sign in.
+    /// Creates an `AuthCredential` for a Game Center sign in.
     ///
     /// The publisher will emit events on the **main** thread.
     ///
@@ -40,4 +40,4 @@
     }
   }
 
-#endif
+#endif // canImport(Combine) && swift(>=5.0) && canImport(FirebaseAuth)