Clean APIs and add more API documentations.

AppAuth.podspec

@@ -57,8 +57,9 @@ It follows the OAuth 2.0 for Native Apps best current practice
     externalUserAgent.ios.weak_frameworks   = "AuthenticationServices"
 
     # macOS
-    externalUserAgent.osx.source_files = "Source/AppAuth/macOS/**/*.{h,m}"
+    externalUserAgent.osx.source_files      = "Source/AppAuth/macOS/**/*.{h,m}"
     externalUserAgent.osx.deployment_target = '10.9'
+    externalUserAgent.osx.weak_frameworks   = "AuthenticationServices"
   end
 
   s.subspec 'EnterpriseUserAgent' do |enterpriseUserAgent|

Examples/Example-macOS/Source/AppAuthExampleViewController.m

@@ -212,22 +212,20 @@ - (IBAction)authWithAutoCodeExchange:(nullable id)sender {
                                                   responseType:OIDResponseTypeCode
                                           additionalParameters:nil];
     // performs authentication request
-    if (@available(macOS 10.15, *)) {
-      self.appDelegate.currentAuthorizationFlow =
-        [OIDAuthState authStateByPresentingAuthorizationRequest:request
-                                               presentingWindow:self.view.window
-                                                       callback:^(OIDAuthState *_Nullable authState,
-                                                                  NSError *_Nullable error) {
-          [self processAuthState:authState error:error];
-      }];
-    } else {
-      self.appDelegate.currentAuthorizationFlow =
+    self.appDelegate.currentAuthorizationFlow =
       [OIDAuthState authStateByPresentingAuthorizationRequest:request
+                                             presentingWindow:self.view.window
                                                      callback:^(OIDAuthState *_Nullable authState,
                                                                 NSError *_Nullable error) {
-        [self processAuthState:authState error:error];
-      }];
-    }
+        if (authState) {
+          [self setAuthState:authState];
+          [self logMessage:@"Got authorization tokens. Access token: %@",
+                           authState.lastTokenResponse.accessToken];
+        } else {
+          [self logMessage:@"Authorization error: %@", [error localizedDescription]];
+          [self setAuthState:nil];
+        }
+    }];
   }];
 }
 
@@ -283,21 +281,24 @@ - (IBAction)authWithAutoCodeExchangeHTTP:(nullable id)sender {
                                           additionalParameters:nil];
     // performs authentication request
     __weak __typeof(self) weakSelf = self;
-
-    if (@available(macOS 10.15, *)) {
-      _redirectHTTPHandler.currentAuthorizationFlow =
-        [OIDAuthState authStateByPresentingAuthorizationRequest:request
-                                               presentingWindow:self.view.window
-                                                       callback:^(OIDAuthState *_Nullable authState, NSError *_Nullable error) {
-        [self processHTTPRedirectAuthState:authState error:error weakSelfReference:weakSelf];
-      }];
-    } else {
-      _redirectHTTPHandler.currentAuthorizationFlow =
-        [OIDAuthState authStateByPresentingAuthorizationRequest:request
-                                                       callback:^(OIDAuthState *_Nullable authState, NSError *_Nullable error) {
-          [self processHTTPRedirectAuthState:authState error:error weakSelfReference:weakSelf];
+    _redirectHTTPHandler.currentAuthorizationFlow =
+      [OIDAuthState authStateByPresentingAuthorizationRequest:request
+                                             presentingWindow:self.view.window
+                                                     callback:^(OIDAuthState *_Nullable authState, NSError *_Nullable error) {
+        // Brings this app to the foreground.
+        [[NSRunningApplication currentApplication]
+            activateWithOptions:(NSApplicationActivateAllWindows |
+                                 NSApplicationActivateIgnoringOtherApps)];
+
+        // Processes the authorization response.
+        if (authState) {
+          [weakSelf logMessage:@"Got authorization tokens. Access token: %@",
+                           authState.lastTokenResponse.accessToken];
+        } else {
+          [weakSelf logMessage:@"Authorization error: %@", error.localizedDescription];
+        }
+        [weakSelf setAuthState:authState];
       }];
-    }
   }];
 }
 
@@ -330,21 +331,22 @@ - (IBAction)authNoCodeExchange:(nullable id)sender {
     // performs authentication request
     [self logMessage:@"Initiating authorization request %@", request];
 
-    if (@available(macOS 10.15, *)) {
-      self.appDelegate.currentAuthorizationFlow =
-          [OIDAuthorizationService presentAuthorizationRequest:request
-                                              presentingWindow:self.view.window
-                                                      callback:^(OIDAuthorizationResponse *_Nullable authorizationResponse, NSError *_Nullable error) {
-        [self processAuthorizationResponse:authorizationResponse error:error];
-      }];
-    } else {
-      self.appDelegate.currentAuthorizationFlow =
-          [OIDAuthorizationService presentAuthorizationRequest:request
-                              callback:^(OIDAuthorizationResponse *_Nullable authorizationResponse,
-                                         NSError *_Nullable error) {
-        [self processAuthorizationResponse:authorizationResponse error:error];
+    self.appDelegate.currentAuthorizationFlow =
+        [OIDAuthorizationService presentAuthorizationRequest:request
+                                            presentingWindow:self.view.window
+                                                    callback:^(OIDAuthorizationResponse *_Nullable authorizationResponse, NSError *_Nullable error) {
+          if (authorizationResponse) {
+            OIDAuthState *authState =
+                [[OIDAuthState alloc] initWithAuthorizationResponse:authorizationResponse];
+            [self setAuthState:authState];
+
+            [self logMessage:@"Authorization response with code: %@",
+                             authorizationResponse.authorizationCode];
+            // could just call [self tokenExchange:nil] directly, but will let the user initiate it.
+          } else {
+            [self logMessage:@"Authorization error: %@", [error localizedDescription]];
+          }
       }];
-    }
   }];
 }
 
@@ -492,49 +494,4 @@ - (void)logMessage:(NSString *)format, ... NS_FORMAT_FUNCTION(1,2) {
   });
 }
 
-- (void)processAuthState:(OIDAuthState *)authState
-                   error:(NSError *)error {
-  if (authState) {
-    [self setAuthState:authState];
-    [self logMessage:@"Got authorization tokens. Access token: %@",
-                     authState.lastTokenResponse.accessToken];
-  } else {
-    [self logMessage:@"Authorization error: %@", [error localizedDescription]];
-    [self setAuthState:nil];
-  }
-}
-
-- (void)processHTTPRedirectAuthState:(OIDAuthState *)authState
-                               error:(NSError *)error
-                   weakSelfReference:(AppAuthExampleViewController *)weakSelf {
-  // Brings this app to the foreground.
-  [[NSRunningApplication currentApplication]
-      activateWithOptions:(NSApplicationActivateAllWindows |
-                           NSApplicationActivateIgnoringOtherApps)];
-
-  // Processes the authorization response.
-  if (authState) {
-    [weakSelf logMessage:@"Got authorization tokens. Access token: %@",
-                     authState.lastTokenResponse.accessToken];
-  } else {
-    [weakSelf logMessage:@"Authorization error: %@", error.localizedDescription];
-  }
-  [weakSelf setAuthState:authState];
-}
-
-- (void)processAuthorizationResponse:(OIDAuthorizationResponse *)authorizationResponse
-                               error:(NSError *)error {
-  if (authorizationResponse) {
-    OIDAuthState *authState =
-        [[OIDAuthState alloc] initWithAuthorizationResponse:authorizationResponse];
-    [self setAuthState:authState];
-
-    [self logMessage:@"Authorization response with code: %@",
-                     authorizationResponse.authorizationCode];
-    // could just call [self tokenExchange:nil] directly, but will let the user initiate it.
-  } else {
-    [self logMessage:@"Authorization error: %@", [error localizedDescription]];
-  }
-}
-
 @end

Source/AppAuth/macOS/OIDAuthState+Mac.h

@@ -41,16 +41,25 @@ NS_ASSUME_NONNULL_BEGIN
     @return A @c OIDExternalUserAgentSession instance which will terminate when it
         receives a @c OIDExternalUserAgentSession.cancel message, or after processing a
         @c OIDExternalUserAgentSession.resumeExternalUserAgentFlowWithURL: message.
+    @discussion This method adopts ASWebAuthenticationSession for macOS 10.15 and above or the default browser otherwise.
  */
 + (id<OIDExternalUserAgentSession>)
     authStateByPresentingAuthorizationRequest:(OIDAuthorizationRequest *)authorizationRequest
                              presentingWindow:(NSWindow *)presentingWindow
-                                     callback:(OIDAuthStateAuthorizationCallback)callback
-                                     API_AVAILABLE(macosx(10.15));
+                                     callback:(OIDAuthStateAuthorizationCallback)callback;
 
+/*! @param authorizationRequest The authorization request to present.
+    @param callback The method called when the request has completed or failed.
+    @return A @c OIDExternalUserAgentSession instance which will terminate when it
+        receives a @c OIDExternalUserAgentSession.cancel message, or after processing a
+        @c OIDExternalUserAgentSession.resumeExternalUserAgentFlowWithURL: message.
+    @discussion This method uses the default browser to present the authentication flow.
+ */
 + (id<OIDExternalUserAgentSession>)
     authStateByPresentingAuthorizationRequest:(OIDAuthorizationRequest *)authorizationRequest
-                                     callback:(OIDAuthStateAuthorizationCallback)callback;
+                                     callback:(OIDAuthStateAuthorizationCallback)callback
+    __deprecated_msg("For macOS 10.15 and above please use "
+        "authStateByPresentingAuthorizationRequest:presentingWindow:callback:");
 
 @end
 

Source/AppAuth/macOS/OIDAuthState+Mac.m

@@ -30,8 +30,7 @@ @implementation OIDAuthState (Mac)
     authStateByPresentingAuthorizationRequest:(OIDAuthorizationRequest *)authorizationRequest
                              presentingWindow:(NSWindow *)presentingWindow
                                      callback:(OIDAuthStateAuthorizationCallback)callback {
-  id<OIDExternalUserAgent> externalUserAgent = [[OIDExternalUserAgentMac alloc] initWithPresentingWindow:presentingWindow];
-
+  OIDExternalUserAgentMac *externalUserAgent = [[OIDExternalUserAgentMac alloc] initWithPresentingWindow:presentingWindow];
   return [self authStateByPresentingAuthorizationRequest:authorizationRequest
                                        externalUserAgent:externalUserAgent
                                                 callback:callback];

Source/AppAuth/macOS/OIDAuthorizationService+Mac.h

@@ -29,20 +29,29 @@ NS_ASSUME_NONNULL_BEGIN
  */
 @interface OIDAuthorizationService (Mac)
 
-/*! @brief Perform an authorization flow using the default browser.
+/*! @brief Perform an authorization flow.
     @param request The authorization request.
     @param presentingWindow The window to present the authentication flow.
     @param callback The method called when the request has completed or failed.
     @return A @c OIDExternalUserAgentSession instance which will terminate when it
         receives a @c OIDExternalUserAgentSession.cancel message, or after processing a
         @c OIDExternalUserAgentSession.resumeExternalUserAgentFlowWithURL: message.
+    @discussion This method adopts  ASWebAuthenticationSession for macOS 10.15 and above or the default browser otherwise.
  */
 + (id<OIDExternalUserAgentSession>) presentAuthorizationRequest:(OIDAuthorizationRequest *)request
                                                presentingWindow:(NSWindow *)presentingWindow
-                                                       callback:(OIDAuthorizationCallback)callback API_AVAILABLE(macosx(10.15));
+                                                       callback:(OIDAuthorizationCallback)callback;
 
+/*! @brief Perform an authorization flow using the default browser.
+    @param request The authorization request.
+    @param callback The method called when the request has completed or failed.
+    @return A @c OIDExternalUserAgentSession instance which will terminate when it
+        receives a @c OIDExternalUserAgentSession.cancel message, or after processing a
+        @c OIDExternalUserAgentSession.resumeExternalUserAgentFlowWithURL: message.
+ */
 + (id<OIDExternalUserAgentSession>)presentAuthorizationRequest:(OIDAuthorizationRequest *)request
-                                                      callback:(OIDAuthorizationCallback)callback;
+                                                      callback:(OIDAuthorizationCallback)callback
+    __deprecated_msg("For macOS 10.15 and above please use presentAuthorizationRequest:presentingWindow:callback:");
 
 @end
 

Source/AppAuth/macOS/OIDExternalUserAgentMac.h

@@ -33,7 +33,9 @@ NS_ASSUME_NONNULL_BEGIN
 /*! @brief The designated initializer.
     @param presentingWindow The window from which to present the ASWebAuthenticationSession.
  */
-- (instancetype)initWithPresentingWindow: (NSWindow *)presentingWindow API_AVAILABLE(macosx(10.15));
+- (instancetype)initWithPresentingWindow:(NSWindow *)presentingWindow NS_DESIGNATED_INITIALIZER;
+
+- (instancetype)init __deprecated_msg("Use initWithPresentingWindow for macOS 10.15 and above.");
 
 @end
 

Source/AppAuth/macOS/OIDExternalUserAgentMac.m

@@ -32,10 +32,8 @@
 
 NS_ASSUME_NONNULL_BEGIN
 
-#if __MAC_OS_X_VERSION_MAX_ALLOWED >= 101500
 @interface OIDExternalUserAgentMac ()<ASWebAuthenticationPresentationContextProviding>
 @end
-#endif // __MAC_OS_X_VERSION_MAX_ALLOWED >= 101500
 
 @implementation OIDExternalUserAgentMac {
   BOOL _externalUserAgentFlowInProgress;
@@ -48,14 +46,21 @@ @implementation OIDExternalUserAgentMac {
 #pragma clang diagnostic pop
 }
 
-- (instancetype)initWithPresentingWindow: (NSWindow *)presentingWindow {
+- (instancetype)initWithPresentingWindow:(NSWindow *)presentingWindow {
   self = [super init];
   if (self) {
     _presentingWindow = presentingWindow;
   }
   return self;
 }
 
+- (instancetype)init {
+#pragma clang diagnostic push
+#pragma clang diagnostic ignored "-Wnonnull"
+  return [self initWithPresentingWindow:nil];
+#pragma clang diagnostic pop
+}
+
 - (BOOL)presentExternalUserAgentRequest:(id<OIDExternalUserAgentRequest>)request
                                 session:(id<OIDExternalUserAgentSession>)session {
   if (_externalUserAgentFlowInProgress) {
@@ -140,13 +145,11 @@ - (void)cleanUp {
   _webAuthenticationSession = nil;
 }
 
-#if __MAC_OS_X_VERSION_MAX_ALLOWED >= 101500
 #pragma mark - ASWebAuthenticationPresentationContextProviding
 
 -(ASPresentationAnchor)presentationAnchorForWebAuthenticationSession:(ASWebAuthenticationSession *)session API_AVAILABLE(macosx(10.15)){
   return _presentingWindow;
 }
-#endif // __MAC_OS_X_VERSION_MAX_ALLOWED >= 101500
 
 @end