chore(auth): Updated code documentation comments (#1265)

Author: royjit

Amplify/Categories/Auth/Error/AuthError.swift

@@ -7,6 +7,7 @@
 
 import Foundation
 
+/// Amplify error raised in the Auth category.
 public enum AuthError {
 
     /// Caused by issue in the way auth category is configured

Amplify/Categories/Auth/Models/AuthCodeDeliveryDetails.swift

@@ -9,6 +9,7 @@ import Foundation
 
 public typealias AdditionalInfo = [String: String]
 
+/// Details on where the code has been delivered
 public struct AuthCodeDeliveryDetails {
 
     /// Destination to which the code was delivered.

Amplify/Categories/Auth/Models/AuthDevice.swift

@@ -7,9 +7,12 @@
 
 import Foundation
 
+/// Device used by the user to sign in
 public protocol AuthDevice {
 
+    /// Device id
     var id: String { get }
 
+    /// Device name
     var name: String { get }
 }

Amplify/Categories/Auth/Models/AuthProvider.swift

@@ -7,19 +7,33 @@
 
 import Foundation
 
+/// Supported auth providers that help in federated sign in
+///
+/// You can use these auth providers to directly sign in to one of the user's social provider and then
+/// federate them to the auth plugin's underlying service. For example in the api
+/// `Amplify.Auth.signInWithWebUI(for:presentationAnchor:)` you can pass in a provider
+/// in the `for:` parameter which will directly show a authentication view for the passed in auth provider.
 public enum AuthProvider {
 
+    /// Auth provider that uses Login with Amazon
     case amazon
 
+    /// Auth provider that uses Sign in with Apple
     case apple
 
+    /// Auth provider that uses Facebook Login
     case facebook
 
+    /// Auth provider that uses Google Sign-In
     case google
 
+    /// Auth provider that uses OpenID Connect Protocol
     case oidc
 
+    /// Auth provider that uses Security Assertion Markup Language standard
     case saml
 
+    /// Custom auth provider that is not in this list, the associated string value will be the identifier used by
+    /// the plugin service.
     case custom(String)
 }

Amplify/Categories/Auth/Models/AuthSession.swift

@@ -7,7 +7,13 @@
 
 import Foundation
 
+/// Defines the auth session behavior
 public protocol AuthSession {
 
+    /// Indicates whether a user is signed in or not
+    ///
+    /// `true` if a user is authenticated. `isSignedIn` remains `true` till we call `Amplify.Auth.signOut`.
+    /// Please note that this value remains `true` even when the session is expired. Refer the underlying plugin
+    /// documentation regarding how to handle session expiry.
     var isSignedIn: Bool { get }
 }

Amplify/Categories/Auth/Models/AuthUpdateAttributeStep.swift

@@ -5,9 +5,16 @@
 // SPDX-License-Identifier: Apache-2.0
 //
 
+/// Step for Auth.updateUserAttribute api call
 public enum AuthUpdateAttributeStep {
 
+    /// Next step is to confirm the attribute with confirmation code.
+    ///
+    /// Invoke Auth.confirm(userAttribute: ...) to confirm the attribute that was updated.
+    /// `AuthCodeDeliveryDetails` provides the details to which the confirmation
+    /// code was send and `AdditionalInfo` will provide more details if present.
     case confirmAttributeWithCode(AuthCodeDeliveryDetails, AdditionalInfo?)
 
+    /// Update Attribute step is `done` when the update attribute flow is complete.
     case done
 }

Amplify/Categories/Auth/Models/AuthUser.swift

@@ -5,10 +5,13 @@
 // SPDX-License-Identifier: Apache-2.0
 //
 
+/// Defines the protocol for an auth user
 public protocol AuthUser {
 
+    /// User name of the auth user
     var username: String { get }
 
+    /// Unique id of the auth user
     var userId: String { get }
 
 }

Amplify/Categories/Auth/Models/AuthUserAttribute.swift

@@ -15,22 +15,54 @@ public struct AuthUserAttribute {
     }
 }
 
+/// Represents the keys used for different user attributes.
+///
 public enum AuthUserAttributeKey {
     // Attribute ref - https://docs.aws.amazon.com/cognito/latest/developerguide/user-pool-settings-attributes.html
+
+    /// Attribute key for user's address
     case address
+
+    /// Attribute key for user's birthdate
     case birthDate
+
+    /// Attribute key for user's email
     case email
+
+    /// Attribute key for user's family name
     case familyName
+
+    /// Attribute key for user's gender
     case gender
+
+    /// Attribute key for user's given name
     case givenName
+
+    /// Attribute key for user's locale
     case locale
+
+    /// Attribute key for user's middle name
     case middleName
+
+    /// Attribute key for user's name
     case name
+
+    /// Attribute key for user's nickname
     case nickname
+
+    /// Attribute key for user's phone number
     case phoneNumber
+
+    /// Attribute key for user's picture
     case picture
+
+    /// Attribute key for user's preferred user name
     case preferredUsername
+
+    /// Attribute key for providing custom attributes
     case custom(String)
+
+    /// Attribute key for representing any other keys not mentioned here
     case unknown(String)
 }
 

Amplify/Categories/Auth/Models/DeliveryDestination.swift

@@ -7,13 +7,18 @@
 
 public typealias Destination = String
 
+/// Destination to where an item (e.g., confirmation code) was delivered
 public enum DeliveryDestination {
 
+    /// Email destination with optional associated value containing the email info
     case email(Destination?)
 
+    /// Phone destination with optional associated value containing the phone number info
     case phone(Destination?)
 
+    /// SMS destination with optional associated value containing the number info
     case sms(Destination?)
 
+    /// Unknown destination with optional associated value destination detail
     case unknown(Destination?)
 }

Amplify/Categories/Auth/Request/AuthAttributeResendConfirmationCodeRequest.swift

@@ -7,11 +7,15 @@
 
 import Foundation
 
-// swiftlint:disable:next type_name
+// swiftlint:disable type_name
+
+/// Request for resending confirmation code that was generated for update attribute
 public struct AuthAttributeResendConfirmationCodeRequest: AmplifyOperationRequest {
 
+    /// Attribute key for which the confirmation code was sent
     public let attributeKey: AuthUserAttributeKey
 
+    /// Extra request options defined in `AuthAttributeResendConfirmationCodeRequest.Options`
     public var options: Options
 
     public init(attributeKey: AuthUserAttributeKey,