[auth-swift] Modernize Auth API docs (#12353)

.github/workflows/auth.yml

@@ -58,7 +58,7 @@ jobs:
 
     env:
       plist_secret: ${{ secrets.GHASecretsGPGPassphrase1 }}
-    runs-on: macos-12
+    runs-on: macos-13
     steps:
     - uses: actions/checkout@v4
     - uses: mikehardy/buildcache-action@c87cea0ccd718971d6cc39e672c4f26815b6c126
@@ -85,7 +85,8 @@ jobs:
           FirebaseAuth/Tests/SampleSwift/Sample.entitlements "$plist_secret"
         scripts/decrypt_gha_secret.sh scripts/gha-encrypted/AuthSample/Credentials.swift.gpg \
           FirebaseAuth/Tests/SampleSwift/SwiftApiTests/Credentials.swift "$plist_secret"
-
+    - name: Xcode
+      run: sudo xcode-select -s /Applications/Xcode_15.1.app/Contents/Developer
     - name: BuildAndTest # can be replaced with pod lib lint with CocoaPods 1.10
       run: ([ -z $plist_secret ] || scripts/third_party/travis/retry.sh scripts/build.sh Auth iOS)
 

FirebaseAuth/Sources/Swift/ActionCode/ActionCodeInfo.swift

@@ -14,24 +14,16 @@
 
 import Foundation
 
-/** @class ActionCodeInfo
-    @brief Manages information regarding action codes.
- */
+/// Manages information regarding action codes.
 @objc(FIRActionCodeInfo) open class ActionCodeInfo: NSObject {
-  /**
-      @brief The operation being performed.
-   */
+  /// The operation being performed.
   @objc public let operation: ActionCodeOperation
 
-  /** @property email
-      @brief The email address to which the code was sent. The new email address in the case of
-          `ActionCodeOperationRecoverEmail`.
-   */
+  /// The email address to which the code was sent. The new email address in the case of
+  /// `ActionCodeOperation.recoverEmail`.
   @objc public let email: String?
 
-  /** @property previousEmail
-      @brief The email that is being recovered in the case of `ActionCodeOperationRecoverEmail`.
-   */
+  /// The email that is being recovered in the case of `ActionCodeOperation.recoverEmail`.
   @objc public let previousEmail: String?
 
   init(withOperation operation: ActionCodeOperation, email: String, newEmail: String?) {
@@ -45,11 +37,9 @@ import Foundation
     }
   }
 
-  /** @fn actionCodeOperationForRequestType:
-      @brief Returns the corresponding operation type per provided request type string.
-      @param requestType Request type returned in in the server response.
-      @return The corresponding ActionCodeOperation for the supplied request type.
-   */
+  /// Map a request type string to the corresponding operation type.
+  /// - Parameter requestType: Request type returned in in the server response.
+  /// - Returns: The corresponding ActionCodeOperation for the supplied request type.
   class func actionCodeOperation(forRequestType requestType: String?) -> ActionCodeOperation {
     switch requestType {
     case "PASSWORD_RESET": return .passwordReset

FirebaseAuth/Sources/Swift/ActionCode/ActionCodeOperation.swift

@@ -14,28 +14,26 @@
 
 import Foundation
 
-/**
-   @brief Operations which can be performed with action codes.
- */
+/// Operations which can be performed with action codes.
 @objc(FIRActionCodeOperation) public enum ActionCodeOperation: Int, @unchecked Sendable {
-  /** Action code for unknown operation. */
+  /// Action code for unknown operation.
   case unknown = 0
 
-  /** Action code for password reset operation. */
+  /// Action code for password reset operation.
   case passwordReset = 1
 
-  /** Action code for verify email operation. */
+  /// Action code for verify email operation.
   case verifyEmail = 2
 
-  /** Action code for recover email operation. */
+  /// Action code for recover email operation.
   case recoverEmail = 3
 
-  /** Action code for email link operation. */
+  /// Action code for email link operation.
   case emailLink = 4
 
-  /** Action code for verifying and changing email */
+  /// Action code for verifying and changing email.
   case verifyAndChangeEmail = 5
 
-  /** Action code for reverting second factor addition */
+  /// Action code for reverting second factor addition.
   case revertSecondFactorAddition = 6
 }

FirebaseAuth/Sources/Swift/ActionCode/ActionCodeSettings.swift

@@ -14,68 +14,49 @@
 
 import Foundation
 
-/** @class FIRActionCodeSettings
-    @brief Used to set and retrieve settings related to handling action codes.
- */
+/// Used to set and retrieve settings related to handling action codes.
 @objc(FIRActionCodeSettings) open class ActionCodeSettings: NSObject {
-  /** @property URL
-      @brief This URL represents the state/Continue URL in the form of a universal link.
-      @remarks This URL can should be constructed as a universal link that would either directly open
-          the app where the action code would be handled or continue to the app after the action code
-          is handled by Firebase.
-   */
+  /// This URL represents the state/Continue URL in the form of a universal link.
+  ///
+  /// This URL can should be constructed as a universal link that would either directly open
+  /// the app where the action code would be handled or continue to the app after the action code
+  /// is handled by Firebase.
   @objc(URL) open var url: URL?
 
-  /** @property handleCodeInApp
-      @brief Indicates whether the action code link will open the app directly or after being
-          redirected from a Firebase owned web widget.
-   */
+  /// Indicates whether the action code link will open the app directly or after being
+  /// redirected from a Firebase owned web widget.
   @objc open var handleCodeInApp: Bool = false
 
-  /** @property iOSBundleID
-      @brief The iOS bundle ID, if available. The default value is the current app's bundle ID.
-   */
+  /// The iOS bundle ID, if available. The default value is the current app's bundle ID.
   @objc open var iOSBundleID: String?
 
-  /** @property androidPackageName
-      @brief The Android package name, if available.
-   */
+  /// The Android package name, if available.
   @objc open var androidPackageName: String?
 
-  /** @property androidMinimumVersion
-      @brief The minimum Android version supported, if available.
-   */
+  /// The minimum Android version supported, if available.
   @objc open var androidMinimumVersion: String?
 
-  /** @property androidInstallIfNotAvailable
-      @brief Indicates whether the Android app should be installed on a device where it is not
-         available.
-   */
+  /// Indicates whether the Android app should be installed on a device where it is not available.
   @objc open var androidInstallIfNotAvailable: Bool = false
 
-  /** @property dynamicLinkDomain
-      @brief The Firebase Dynamic Link domain used for out of band code flow.
-   */
+  /// The Firebase Dynamic Link domain used for out of band code flow.
   @objc open var dynamicLinkDomain: String?
 
-  /** @fn
-      @brief Sets the iOS bundle Id.
-   */
-
+  /// Sets the iOS bundle ID.
   @objc override public init() {
     iOSBundleID = Bundle.main.bundleIdentifier
   }
 
-  /** @fn
-      @brief Sets the Android package name, the flag to indicate whether or not to install the app
-          and the minimum Android version supported.
-      @param androidPackageName The Android package name.
-      @param installIfNotAvailable Indicates whether or not the app should be installed if not
-          available.
-      @param minimumVersion The minimum version of Android supported.
-      @remarks If installIfNotAvailable is set to YES and the link is opened on an android device, it
-          will try to install the app if not already available. Otherwise the web URL is used.
-   */
+  /// Sets the Android package name, the flag to indicate whether or not to install the app,
+  /// and the minimum Android version supported.
+  ///
+  /// If `installIfNotAvailable` is set to `true` and the link is opened on an android device, it
+  /// will try to install the app if not already available. Otherwise the web URL is used.
+  /// - Parameters:
+  ///   - androidPackageName: The Android package name.
+  ///   - installIfNotAvailable: Indicates whether or not the app should be installed if not
+  /// available.
+  ///   - minimumVersion: The minimum version of Android supported.
   @objc open func setAndroidPackageName(_ androidPackageName: String,
                                         installIfNotAvailable: Bool,
                                         minimumVersion: String?) {
@@ -84,6 +65,7 @@ import Foundation
     androidMinimumVersion = minimumVersion
   }
 
+  /// Sets the iOS bundle ID.
   open func setIOSBundleID(_ bundleID: String) {
     iOSBundleID = bundleID
   }

FirebaseAuth/Sources/Swift/ActionCode/ActionCodeURL.swift

@@ -14,41 +14,29 @@
 
 import Foundation
 
-/** @class FIRActionCodeURL
-    @brief This class will allow developers to easily extract information about out of band links.
- */
+/// This class will allow developers to easily extract information about out of band links.
 @objc(FIRActionCodeURL) open class ActionCodeURL: NSObject {
-  /** @property APIKey
-      @brief Returns the API key from the link. nil, if not provided.
-   */
+  /// Returns the API key from the link. nil, if not provided.
   @objc(APIKey) public let apiKey: String?
 
-  /** @property operation
-      @brief Returns the mode of oob action. The property will be of `FIRActionCodeOperation` type.
-          It will return `FIRActionCodeOperationUnknown` if no oob action is provided.
-   */
+  /// Returns the mode of oob action.
+  ///
+  /// The property will be of `ActionCodeOperation` type.
+  /// It will return `.unknown` if no oob action is provided.
   @objc public let operation: ActionCodeOperation
 
-  /** @property code
-      @brief Returns the email action code from the link. nil, if not provided.
-   */
+  /// Returns the email action code from the link. nil, if not provided.
   @objc public let code: String?
 
-  /** @property continueURL
-      @brief Returns the continue URL from the link. nil, if not provided.
-   */
+  /// Returns the continue URL from the link. nil, if not provided.
   @objc public let continueURL: URL?
 
-  /** @property languageCode
-      @brief Returns the language code from the link. nil, if not provided.
-   */
+  /// Returns the language code from the link. nil, if not provided.
   @objc public let languageCode: String?
 
-  /** @fn actionCodeURLWithLink:
-      @brief Construct an `ActionCodeURL` from an out of band link (e.g. email link).
-      @param link The oob link string used to construct the action code URL.
-      @return The `ActionCodeURL` object constructed based on the oob link provided.
-   */
+  /// Construct an `ActionCodeURL` from an out of band link (e.g. email link).
+  /// - Parameter link: The oob link string used to construct the action code URL.
+  /// - Returns: The ActionCodeURL object constructed based on the oob link provided.
   @objc(actionCodeURLWithLink:) public init?(link: String) {
     var queryItems = ActionCodeURL.parseURL(link)
     if queryItems.count == 0 {