Expanded Auth documentation

Auth0/AuthProvider.swift

@@ -28,10 +28,10 @@ import UIKit
  model for a given connection name with its own native implementation.
 
  ```
- struct SocialNativeAuth: AuthProvider {
+ struct Facebook: AuthProvider {
 
      func login(withConnection connection: String, scope: String, parameters: [String : Any]) -> NativeAuthTransaction {
-         let transaction = SocialNativeAuthTransaction()
+         let transaction = FacebookNativeAuthTransaction()
          ...
          return transaction
      }

Auth0/NativeAuth.swift

@@ -35,40 +35,71 @@ public struct NativeAuthCredentials {
 
 /**
  The NativeAuthTransaction expands on the AuthTransaction protocol to add additional functionality
- required for handling Native Authentication scenarios.
+ required for handling Native Authentication scenarios. You will need to implement this protocol's
+ properties and methods to handle your Social IdP authentication transaction and yield `NativeAuthCredentials`
+ to be handled by Auth0's `authentication().loginSocial(...)` yielding the Auth0 user's credentials.
 
- The auth func handles the result from the IdP SDK authentication callback.
+ **Properties**
+
+ `connection:` name of the social connection.
+
+ `scope:`      requested scope value when authenticating the user.
+
+ `parameters:` additional parameters sent during authentication.
+
+ `delayed:`    callback that takes a `Result<NativeAuthCredentials>` to handle the outcome from the Social IdP authentication.
+
+ **Methods**
+
+ `func auth(callback: @escaping NativeAuthTransaction.Callback)`
+
+ In this method you should deal with the Social IdP SDKssign in login process. Upon a successful
+ authentication event, you should yield a `NativeAuthCredentials` `Result` to the `callback` containing
+ the OAuth2 access token from the IdP and any extras that may be necessary for Auth0 to authenticate with
+ the chosen IdP. If the authentication was not a success then yield an `Error` `Result`.
 
- Scope, connnection and parameters are used in the final stage of Auth Transaction during the Auth0 Social Authentication.
+
+ `func cancel()`
+
+ In this method you should deal with the cancellation of the IdP authentication, if your IdP SDK requires
+ any extra steps to cancel this would be a good place to add them.
+
+ `func resume(_ url: URL, options: [UIApplicationOpenURLOptionsKey : Any]) -> Bool`
 
+ In this method you should handle the continuation of the IdP's authentication process that occurs once control
+ is returned back to the application through the `AppDelegate`
+ Typically this is a call to the IdP SDKs own handler.
+
+ **Example**
+
  ```
- class SocialNativeTransaction: NativeAuthTransaction {
+ class FacebookNativeAuthTransaction: NativeAuthTransaction {
 
-     var connection: String = "social"
+     var connection: String = "facebook"
      var scope: String = "openid"
      var parameters: [String : Any] = [:]
-
      var delayed: NativeAuthTransaction.Callback = { _ in }
 
      func auth(callback: @escaping NativeAuthTransaction.Callback) {
-         NativeSDK.login()
-         self.delayed = callback
+         LoginManager().logIn([.publicProfile]) { result in
+             case .success(_, _, let token):
+                 self.delayed(.success(result: NativeAuthCredentials(token: token.authenticationToken, extras: [:])))
+             case .failed(let error):
+                 self.delayed(.failure(error: error))
+             case .cancelled:
+                 self.cancel()
+             }
      }
 
      func cancel() {
          self.delayed(.failure(error: WebAuthError.userCancelled))
-         self.delayed = { _ in }
      }
 
      func resume(_ url: URL, options: [UIApplicationOpenURLOptionsKey : Any]) -> Bool {
-         return NativeSDK.Resume() {
-             self.delayed(.success(NativeAuthCredentials(token: NativeSDK.OAuth2Token, extras: [:])))
-             self.delayed = { _ in }
-         }
+         return SDKApplicationDelegate.shared.application(app, open: url, options: options)
      }
  }
  ```
-
  */
 public protocol NativeAuthTransaction: AuthTransaction {
     var scope: String { get }