Update API docs (#816)

Auth0/Auth0.swift

@@ -93,10 +93,10 @@ public func authentication(session: URLSession = .shared, bundle: Bundle = .main
  Auth0.users(token: credentials.accessToken)
  ```
 
- Currently you can only perform the following operations:
+ You can only perform the following operations:
 
  * Get a user by ID
- * Update an user, for example by adding `user_metadata`
+ * Update the user's `user_metadata`
  * Link users
  * Unlink users
 
@@ -137,10 +137,10 @@ public func users(token: String, session: URLSession = .shared, bundle: Bundle =
  Auth0.users(token: credentials.accessToken, domain: "samples.us.auth0.com")
  ```
 
- Currently you can only perform the following operations:
+ You can only perform the following operations:
 
  * Get a user by ID
- * Update an user, for example by adding `user_metadata`
+ * Update the user's `user_metadata`
  * Link users
  * Unlink users
 

Auth0/Credentials.swift

@@ -44,8 +44,9 @@ public final class Credentials: NSObject {
     ///
     /// - Important: The ID tokens obtained from Web Auth login are automatically validated by Auth0.swift, ensuring their
     /// contents have not been tampered with. **This is not the case for the ID tokens obtained from the Authentication API
-    /// client.** You must [validate](https://auth0.com/docs/secure/tokens/id-tokens/validate-id-tokens) any ID
-    /// Tokens received from the Authentication API client before using the information they contain.
+    /// client**, including the ones received when renewing the credentials using the refresh token. You must
+    /// [validate](https://auth0.com/docs/secure/tokens/id-tokens/validate-id-tokens) any ID tokens received from the
+    /// Authentication API client before using the information they contain.
     ///
     /// ## See Also
     ///

Auth0/CredentialsManager.swift

@@ -10,9 +10,10 @@ import LocalAuthentication
 
 /// Credentials management utility for securely storing and retrieving the user's credentials from the Keychain.
 ///
-/// - Warning: The Credentials Manager is not thread-safe, except for the
-/// ``CredentialsManager/credentials(withScope:minTTL:parameters:headers:callback:)`` method. Do not call its non
-/// thread-safe methods and properties from different threads without proper synchronization.
+/// - Warning: The Credentials Manager is not thread-safe, except for its
+/// ``CredentialsManager/credentials(withScope:minTTL:parameters:headers:callback:)`` and
+/// ``CredentialsManager/renew(parameters:headers:callback:)`` methods. To avoid concurrency issues, do not call its
+/// non thread-safe methods and properties from different threads without proper synchronization.
 ///
 /// ## See Also
 ///

Auth0/SafariProvider.swift

@@ -17,7 +17,7 @@ public extension WebAuthentication {
     /// }
     /// ```
     ///
-    /// If you need specify a custom `UIModalPresentationStyle`:
+    /// If you need to specify a custom `UIModalPresentationStyle`:
     ///
     /// ```swift
     /// Auth0
@@ -30,6 +30,10 @@ public extension WebAuthentication {
     ///
     /// - Parameter style: `UIModalPresentationStyle` to be used. Defaults to `.fullScreen`.
     /// - Returns: A ``WebAuthProvider`` instance.
+    ///
+    /// ## See Also
+    ///
+    /// - <doc:UserAgents>
     static func safariProvider(style: UIModalPresentationStyle = .fullScreen) -> WebAuthProvider {
         return { url, callback in
             let safari = SFSafariViewController(url: url)

Auth0/WebAuth.swift

@@ -138,6 +138,7 @@ public protocol WebAuth: Trackable, Loggable {
     ///
     /// ## See Also
     ///
+    /// - <doc:UserAgents>
     /// - [FAQ](https://github.com/auth0/Auth0.swift/blob/master/FAQ.md)
     /// - [prefersEphemeralWebBrowserSession](https://developer.apple.com/documentation/authenticationservices/aswebauthenticationsession/3237231-prefersephemeralwebbrowsersessio)
     func useEphemeralSession() -> Self
@@ -163,6 +164,7 @@ public protocol WebAuth: Trackable, Loggable {
     ///
     /// ## See Also
     ///
+    /// - <doc:UserAgents>
     /// - ``WebAuthProvider``
     func provider(_ provider: @escaping WebAuthProvider) -> Self
 

Documentation.docc/WebAuth/UserAgents.md

@@ -1,8 +1,8 @@
-# ASWebAuthenticationSession vs SFSafariViewController
+# ASWebAuthenticationSession vs SFSafariViewController (iOS)
 
 ## Overview
 
-Web-based authentication needs a browser. Auth0.swift offers the choice of two system-provided browser APIs: [`ASWebAuthenticationSession`](https://developer.apple.com/documentation/authenticationservices/aswebauthenticationsession) and [`SFSafariViewController`](https://developer.apple.com/documentation/safariservices/sfsafariviewcontroller).
+Web-based authentication needs an in-app browser. Auth0.swift offers the choice of two system-provided browser APIs: [`ASWebAuthenticationSession`](https://developer.apple.com/documentation/authenticationservices/aswebauthenticationsession) and [`SFSafariViewController`](https://developer.apple.com/documentation/safariservices/sfsafariviewcontroller).
 
 ## When to use ASWebAuthenticationSession
 
@@ -64,7 +64,7 @@ Auth0
     }
 ```
 
-`SFSafariViewController` is a general purpose in-app browser that can also be used to perform web-based authentication. When used for this purpose, it acts as a middle ground between `ASWebAuthenticationSession` with/without ephemeral sessions. It persists cookies, but won't share them outside of your app. This means that:
+`SFSafariViewController` is a general purpose in-app browser that can also be used to perform web-based authentication. When used for this purpose, it acts as a middle ground between `ASWebAuthenticationSession` with and without ephemeral sessions. It persists cookies, but won't share them outside of your app. This means that:
 
 - All the `SFSafariViewController` instances used in your app will have access to the persisted session cookie.
 - No consent alert box will be shown, as the session cookie won't be placed in a shared cookie jar.

EXAMPLES.md

@@ -1295,10 +1295,8 @@ Auth0
                     .webAuth()
                     .connection(connection)
                     .scope(scope)
-                    .useEphemeralSession()
-                    // ☝🏼 Otherwise a session cookie will remain
-                    .parameters(["login_hint": email])
-                    // ☝🏼 So the user doesn't have to type it again
+                    .useEphemeralSession() // Otherwise a session cookie will remain
+                    .parameters(["login_hint": email]) // So the user doesn't have to type it again
                     .start { result in
                         // ...
                     }