Fixed up the documentation.

– Sync'd the headers exposed in AppAuth.h with the classes publicly documented in Doxygen. – Added macOS and iOS classes to docs. – Fixed missing references. – Added some external links to Apple's docs.
lucasrodriguesus · Nov 8, 2016 · 04ceca3 · 04ceca3
1 parent 0dbffe7
commit 04ceca3
Show file tree

Hide file tree

Showing 16 changed files with 97 additions and 33 deletions.
diff --git a/.gitignore b/.gitignore
@@ -0,0 +1 @@
+Docs/
diff --git a/Doxyfile b/Doxyfile
@@ -38,12 +38,12 @@ INHERIT_DOCS           = YES
 SEPARATE_MEMBER_PAGES  = NO
 TAB_SIZE               = 4
 # Alias external references. ref: http://stackoverflow.com/a/24076896/72176
-ALIASES                += SFSafariViewController="<code><a href=\"https://developer.apple.com/library/ios/documentation/SafariServices/Reference/SFSafariViewController_Ref/index.html\">SFSafariViewController</a></code>"
-ALIASES                += NSURLSession="<code><a href=\"https://developer.apple.com/library/ios/documentation/Foundation/Reference/NSURLSession_class/\">NSURLSession</a></code>"
-ALIASES                += NSError_userInfo="<code><a href=\"https://developer.apple.com/library/mac/documentation/Cocoa/Reference/Foundation/Classes/NSError_Class/#//apple_ref/occ/instp/NSError/userInfo\">NSError.userInfo</a></code>"
-ALIASES                += NSError_code="<code><a href=\"https://developer.apple.com/library/mac/documentation/Cocoa/Reference/Foundation/Classes/NSError_Class/#//apple_ref/occ/instp/NSError/code\">NSError.code</a></code>"
-ALIASES                += NSError="<code><a href=\"https://developer.apple.com/library/ios/documentation/Cocoa/Reference/Foundation/Classes/NSError_Class/\">NSError</a></code>"
-ALIASES                += NSHTTPURLResponse="<code><a href=\"https://developer.apple.com/library/ios/documentation/Cocoa/Reference/Foundation/Classes/NSHTTPURLResponse_Class/\">NSHTTPURLResponse</a></code>"
+ALIASES                += SFSafariViewController="<code><a href=\"https://developer.apple.com/reference/safariservices/sfsafariviewcontroller\">SFSafariViewController</a></code>"
+ALIASES                += NSURLSession="<code><a href=\"https://developer.apple.com/reference/foundation/urlsession\">NSURLSession</a></code>"
+ALIASES                += NSError_userInfo="<code><a href=\"https://developer.apple.com/reference/foundation/nserror/1411580-userinfo\">NSError.userInfo</a></code>"
+ALIASES                += NSError_code="<code><a href=\"https://developer.apple.com/reference/foundation/nserror/1409165-code\">NSError.code</a></code>"
+ALIASES                += NSError="<code><a href=\"https://developer.apple.com/reference/foundation/nserror\">NSError</a></code>"
+ALIASES                += NSHTTPURLResponse="<code><a href=\"https://developer.apple.com/reference/foundation/httpurlresponse\">NSHTTPURLResponse</a></code>"
 TCL_SUBST              = 
 OPTIMIZE_OUTPUT_FOR_C  = NO
 OPTIMIZE_OUTPUT_JAVA   = NO
@@ -163,11 +163,17 @@ FILE_PATTERNS          = *.c \
                          *.qsf \
                          *.as \
                          *.js
-RECURSIVE              = NO
+RECURSIVE              = YES
 EXCLUDE                = 
 EXCLUDE_SYMLINKS       = NO
-EXCLUDE_PATTERNS       = *.m # exclude .m files
-EXCLUDE_SYMBOLS        = *() # exclude private categories
+# Excludes .m files
+EXCLUDE_PATTERNS       = *.m
+# Excludes private classes
+EXCLUDE_PATTERNS       += */LoopbackHTTPServer/*
+EXCLUDE_PATTERNS       += */OIDURLQueryComponent.h
+EXCLUDE_PATTERNS       += */OIDFieldMapping.h
+# Excludes private categories
+EXCLUDE_SYMBOLS        = *() 
 EXAMPLE_PATH           = 
 EXAMPLE_PATTERNS       = *
 EXAMPLE_RECURSIVE      = NO

diff --git a/Example-Mac/.gitignore b/Example-Mac/.gitignore
@@ -0,0 +1,24 @@
+## Build generated
+build/
+DerivedData/
+
+## Various settings
+*.pbxuser
+!default.pbxuser
+*.mode1v3
+!default.mode1v3
+*.mode2v3
+!default.mode2v3
+*.perspectivev3
+!default.perspectivev3
+xcuserdata/
+
+## Other
+*.moved-aside
+*.xcuserstate
+
+# Pods are ignored in the samples as all Pods & their dependencies are either
+# development Pods (this repo) or sourced from repos in the same organization.
+# Generally we recommend versioning Pods, see the pros & cons here:
+# https://guides.cocoapods.org/using/using-cocoapods.html#should-i-check-the-pods-directory-into-source-control
+Pods
diff --git a/Example/.gitignore b/Example/.gitignore
@@ -0,0 +1,24 @@
+## Build generated
+build/
+DerivedData/
+
+## Various settings
+*.pbxuser
+!default.pbxuser
+*.mode1v3
+!default.mode1v3
+*.mode2v3
+!default.mode2v3
+*.perspectivev3
+!default.perspectivev3
+xcuserdata/
+
+## Other
+*.moved-aside
+*.xcuserstate
+
+# Pods are ignored in the samples as all Pods & their dependencies are either
+# development Pods (this repo) or sourced from repos in the same organization.
+# Generally we recommend versioning Pods, see the pros & cons here:
+# https://guides.cocoapods.org/using/using-cocoapods.html#should-i-check-the-pods-directory-into-source-control
+Pods
diff --git a/Source/AppAuth.h b/Source/AppAuth.h
@@ -28,10 +28,12 @@
 #import "OIDGrantTypes.h"
 #import "OIDResponseTypes.h"
 #import "OIDScopes.h"
+#import "OIDScopeUtilities.h"
 #import "OIDServiceConfiguration.h"
 #import "OIDServiceDiscovery.h"
 #import "OIDTokenRequest.h"
 #import "OIDTokenResponse.h"
+#import "OIDTokenUtilities.h"
 
 #if TARGET_OS_TV
 #elif TARGET_OS_WATCH
@@ -49,11 +51,11 @@
 #endif
 
 
-/*! @mainpage AppAuth for iOS
+/*! @mainpage AppAuth for iOS and macOS
 
     @section introduction Introduction
 
-    AppAuth for iOS is a client SDK for communicating with [OAuth 2.0]
+    AppAuth for iOS and macOS is a client SDK for communicating with [OAuth 2.0]
     (https://tools.ietf.org/html/rfc6749) and [OpenID Connect]
     (http://openid.net/specs/openid-connect-core-1_0.html) providers. It strives to
     directly map the requests and responses of those specifications, while following

diff --git a/Source/OIDAuthState.h b/Source/OIDAuthState.h
@@ -90,7 +90,7 @@ typedef void (^OIDAuthStateAuthorizationCallback)(OIDAuthState *_Nullable authSt
         @c OIDAuthState.updateWithAuthorizationError: that invalidated this @c OIDAuthState.
         Authorization errors from @c OIDAuthState will always have a domain of
         @c ::OIDOAuthAuthorizationErrorDomain or @c ::OIDOAuthTokenErrorDomain. Note: that after
-        unarchiving the @c OIDAuthState object, the @ NSError.userInfo property of this error will
+        unarchiving the @c OIDAuthState object, the \NSError_userInfo property of this error will
         be nil.
  */
 @property(nonatomic, readonly, nullable) NSError *authorizationError;
@@ -192,9 +192,9 @@ typedef void (^OIDAuthStateAuthorizationCallback)(OIDAuthState *_Nullable authSt
         @c #errorDelegate will be called with the error.
         You may optionally use the convenience method
         OIDErrorUtilities.resourceServerAuthorizationErrorWithCode:errorResponse:underlyingError:
-        to create @c NSError objects for use here.
+        to create \NSError objects for use here.
         The latest error received is stored in @c #authorizationError. Note: that after unarchiving
-        this object, the @c NSError.userInfo property of this error will be nil.
+        this object, the \NSError_userInfo property of this error will be nil.
  */
 - (void)updateWithAuthorizationError:(NSError *)authorizationError;
 

diff --git a/Source/OIDAuthorizationRequest.h b/Source/OIDAuthorizationRequest.h
@@ -182,7 +182,7 @@ extern NSString *const OIDOAuthorizationRequestCodeChallengeMethodS256;
              responseType:(NSString *)responseType
      additionalParameters:(nullable NSDictionary<NSString *, NSString *> *)additionalParameters;
 
-/*! @fn initWithConfiguration:clientId:scope:redirectURL:responseType:state:codeVerifier:codeChallenge:codeChallengeMethod:additionalParameters:
+/*! @fn initWithConfiguration:clientId:clientSecret:scope:redirectURL:responseType:state:codeVerifier:codeChallenge:codeChallengeMethod:additionalParameters:
     @brief Designated initializer.
     @param configuration The service's configuration.
     @param clientID The client identifier.

diff --git a/Source/OIDAuthorizationService.h b/Source/OIDAuthorizationService.h
@@ -63,8 +63,8 @@ typedef void (^OIDTokenCallback)(OIDTokenResponse *_Nullable tokenResponse,
 typedef NSDictionary<NSString *, NSString *> *_Nullable OIDTokenEndpointParameters;
 
 /*! @class OIDAuthorizationService
-    @brief Performs various OAuth and OpenID Connect related RPCs via @c SFSafariViewController or
-        @c NSURLSession.
+    @brief Performs various OAuth and OpenID Connect related calls via the user agent or
+        \NSURLSession.
  */
 @interface OIDAuthorizationService : NSObject
 
@@ -145,11 +145,12 @@ typedef NSDictionary<NSString *, NSString *> *_Nullable OIDTokenEndpointParamete
 - (void)cancel;
 
 /*! @brief Clients should call this method with the result of the authorization code flow if it
-        becomes available. Causes the @c SFSafariViewController created by the
-        @c OIDAuthorizationService::presentAuthorizationRequest:presentingViewController:callback:
-        method to be dismissed, the pending request's completion block is invoked, and this method
-        returns.
+        becomes available.
     @param URL The redirect URL invoked by the authorization server.
+    @discussion When the URL represented a valid authorization response, implementations
+        should clean up any left-over UI state from the authorization, for example by
+        closing the \SFSafariViewController or looback HTTP listener if those were used.
+        The completion block of the pending authorization request should then be invoked.
     @remarks Has no effect if called more than once, or after a @c cancel message was received.
     @return YES if the passed URL matches the expected redirect URL and was consumed, NO otherwise.
  */

diff --git a/Source/OIDAuthorizationUICoordinator.h b/Source/OIDAuthorizationUICoordinator.h
@@ -29,8 +29,7 @@ NS_ASSUME_NONNULL_BEGIN
  */
 @protocol OIDAuthorizationUICoordinator<NSObject>
 
-/*! @fn presentAuthorizationWithURL:session:
-    @brief Presents the authorization UI for the given URL.
+/*! @brief Presents the authorization UI for the given URL.
     @param URL The URL that should be used when presenting the authorization UI.
     @param session The @c OIDAuthorizationFlowSession instance that initiates presenting the
         authorization UI. Concrete implementations of a @c OIDAuthorizationUICoordinator may call
@@ -40,8 +39,7 @@ NS_ASSUME_NONNULL_BEGIN
  */
 - (BOOL)presentAuthorizationWithURL:(NSURL *)URL session:(id<OIDAuthorizationFlowSession>)session;
 
-/*! @fn dismissAuthorizationAnimated:completion:
-    @brief Dimisses the authorization UI and calls completion when the dismiss operation ends.
+/*! @brief Dimisses the authorization UI and calls completion when the dismiss operation ends.
     @param animated Wheter or not the dismiss operation should be animated.
     @remarks Has no effect if no authorization UI is presented.
     @param completion The block to be called when the dismiss operations ends

diff --git a/Source/OIDTokenRequest.h b/Source/OIDTokenRequest.h
@@ -113,7 +113,7 @@ NS_ASSUME_NONNULL_BEGIN
  */
 - (nullable instancetype)init NS_UNAVAILABLE;
 
-/*! @fn initWithConfiguration:grantType:authorizationCode:redirectURL:clientID:scopes:refreshToken:codeVerifier:additionalParameters:
+/*! @fn initWithConfiguration:grantType:authorizationCode:redirectURL:clientID:clientSecret:scopes:refreshToken:codeVerifier:additionalParameters:
     @param configuration The service's configuration.
     @param grantType the type of token being sent to the token endpoint, i.e. "authorization_code"
         for the authorization code exchange, or "refresh_token" for an access token refresh request.
@@ -136,7 +136,7 @@ NS_ASSUME_NONNULL_BEGIN
             codeVerifier:(nullable NSString *)codeVerifier
     additionalParameters:(nullable NSDictionary<NSString *, NSString *> *)additionalParameters;
 
-/*! @fn initWithConfiguration:grantType:authorizationCode:redirectURL:clientID:scope:refreshToken:codeVerifier:additionalParameters:
+/*! @fn initWithConfiguration:grantType:authorizationCode:redirectURL:clientID:clientSecret:scope:refreshToken:codeVerifier:additionalParameters:
     @brief Designated initializer.
     @param configuration The service's configuration.
     @param grantType the type of token being sent to the token endpoint, i.e. "authorization_code"

diff --git a/Source/iOS/OIDAuthState+IOS.h b/Source/iOS/OIDAuthState+IOS.h
@@ -22,6 +22,8 @@
 
 NS_ASSUME_NONNULL_BEGIN
 
+/*! @brief iOS specific convenience methods for @c OIDAuthState.
+ */
 @interface OIDAuthState (IOS)
 
 /*! @fn authStateByPresentingAuthorizationRequest:presentingViewController:callback:

diff --git a/Source/iOS/OIDAuthorizationService+IOS.h b/Source/iOS/OIDAuthorizationService+IOS.h
@@ -22,13 +22,15 @@
 
 NS_ASSUME_NONNULL_BEGIN
 
+/*! @brief Provides iOS specific authorization request handling.
+ */
 @interface OIDAuthorizationService (IOS)
 
 /*! @fn presentAuthorizationRequest:presentingViewController:callback:
-    @brief Perform an authorization flow using @c SFSafariViewController.
+    @brief Perform an authorization flow using \SFSafariViewController.
     @param request The authorization request.
     @param presentingViewController The view controller from which to present the
-        @c SFSafariViewController.
+        \SFSafariViewController.
     @param callback The method called when the request has completed or failed.
     @return A @c OIDAuthorizationFlowSession instance which will terminate when it
         receives a @c OIDAuthorizationFlowSession.cancel message, or after processing a

diff --git a/Source/iOS/OIDAuthorizationUICoordinatorIOS.h b/Source/iOS/OIDAuthorizationUICoordinatorIOS.h
@@ -23,7 +23,7 @@
 NS_ASSUME_NONNULL_BEGIN
 
 /*! @class OIDAuthorizationUICoordinatorIOS
-    @brief An iOS specific authorization UI Coordinator that uses a @c SFSafariViewController to
+    @brief An iOS specific authorization UI Coordinator that uses a \SFSafariViewController to
         present an authorization request.
  */
 @interface OIDAuthorizationUICoordinatorIOS : NSObject<OIDAuthorizationUICoordinator>
@@ -37,7 +37,7 @@ NS_ASSUME_NONNULL_BEGIN
 /*! @fn initWithPresentingViewController:
     @brief The designated initializer.
     @param presentingViewController The view controller from which to present the
-        @c SFSafariViewController.
+        \SFSafariViewController.
  */
 - (nullable instancetype)initWithPresentingViewController:(UIViewController *)parentViewController
     NS_DESIGNATED_INITIALIZER;

diff --git a/Source/macOS/OIDAuthState+Mac.h b/Source/macOS/OIDAuthState+Mac.h
@@ -20,6 +20,8 @@
 
 NS_ASSUME_NONNULL_BEGIN
 
+/*! @brief macOS specific convenience methods for @c OIDAuthState.
+ */
 @interface OIDAuthState (Mac)
 
 /*! @fn authStateByPresentingAuthorizationRequest:callback:

diff --git a/Source/macOS/OIDAuthorizationService+Mac.h b/Source/macOS/OIDAuthorizationService+Mac.h
@@ -20,6 +20,8 @@
 
 NS_ASSUME_NONNULL_BEGIN
 
+/*! @brief Provides macOS specific authorization request handling.
+ */
 @interface OIDAuthorizationService (Mac)
 
 /*! @fn presentAuthorizationRequest:callback:

diff --git a/Source/macOS/OIDRedirectHTTPHandler.h b/Source/macOS/OIDRedirectHTTPHandler.h
@@ -22,8 +22,8 @@ NS_ASSUME_NONNULL_BEGIN
 
 @protocol OIDAuthorizationFlowSession;
 
-/*! @brief Start a HTTP server on the loopback interface (e.g. 127.0.0.1) to receive OAuth
-        authorization result redirects.
+/*! @brief Start a HTTP server on the loopback interface (i.e. @c 127.0.0.1) to receive OAuth
+        authorization response redirects on macOS.
  */
 @interface OIDRedirectHTTPHandler : NSObject