Added links in the Doxygen docs to external classes like SFSafariView…

…Controller.
lucasrodriguesus · Feb 22, 2016 · 0b69c29 · 0b69c29
1 parent c0b8ff6
commit 0b69c29
Show file tree

Hide file tree

Showing 7 changed files with 35 additions and 29 deletions.
diff --git a/Doxyfile b/Doxyfile
@@ -37,7 +37,13 @@ MULTILINE_CPP_IS_BRIEF = NO
 INHERIT_DOCS           = YES
 SEPARATE_MEMBER_PAGES  = NO
 TAB_SIZE               = 4
-ALIASES                = 
+# 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>"
 TCL_SUBST              = 
 OPTIMIZE_OUTPUT_FOR_C  = NO
 OPTIMIZE_OUTPUT_JAVA   = NO

diff --git a/Example/Source/AppDelegate.h b/Example/Source/AppDelegate.h
@@ -30,7 +30,7 @@
 @property(nonatomic, strong, nullable) UIWindow *window;
 
 /*! @property currentAuthorizationFlow
-    @brief The authorization flow session which receives the return URL from SFSafariViewController.
+    @brief The authorization flow session which receives the return URL from \SFSafariViewController.
     @discussion We need to store this in the app delegate as it's that delegate which receives the
         incoming URL on UIApplicationDelegate.application:openURL:options:. This property will be
         nil, except when an authorization flow is in progress.

diff --git a/Source/OIDAuthState.h b/Source/OIDAuthState.h
@@ -89,7 +89,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;
@@ -125,7 +125,7 @@ typedef void (^OIDAuthStateAuthorizationCallback)(OIDAuthState *_Nullable authSt
         and performing the authorization code exchange in the case of code flow requests.
     @param authorizationRequest The authorization request to present.
     @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
@@ -191,9 +191,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/OIDAuthStateErrorDelegate.h b/Source/OIDAuthStateErrorDelegate.h
@@ -32,7 +32,7 @@ NS_ASSUME_NONNULL_BEGIN
     @param error The authorization error.
     @discussion This is a hard error (not a transient network issue) that indicates a problem with
         the authorization. You should stop using the @c OIDAuthState when such an error is
-        encountered. If the @c NSError.error code is @c ::OIDErrorCodeOAuthInvalidGrant then
+        encountered. If the \NSError_code is @c ::OIDErrorCodeOAuthInvalidGrant then
         the session may be recoverable with user interaction (i.e. re-authentication). In all cases
         you should consider the user unauthorized, and remove locally cached resources that require
         that authorization.  @c OIDAuthState will call this method automatically if it encounters

diff --git a/Source/OIDAuthorizationService.h b/Source/OIDAuthorizationService.h
@@ -62,8 +62,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 RPCs via \SFSafariViewController or
+        \NSURLSession.
  */
 @interface OIDAuthorizationService : NSObject
 
@@ -106,10 +106,10 @@ typedef NSDictionary<NSString *, NSString *> *_Nullable OIDTokenEndpointParamete
                                          completion:(OIDDiscoveryCallback)completion;
 
 /*! @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
@@ -144,7 +144,7 @@ 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
+        becomes available. Causes the \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.

diff --git a/Source/OIDError.h b/Source/OIDError.h
@@ -30,8 +30,8 @@ extern NSString *const OIDGeneralErrorDomain;
         with an explicit OAuth error, as defined by RFC6749 Section 4.1.2.1. If the authorization
         response is invalid and not explicitly an error response, another error domain will be used.
         The error response parameter dictionary is available in the
-        @c NSError.userInfo dictionary using the @c ::OIDOAuthErrorResponseErrorKey key.
-        The @c NSError.code will be one of the @c ::OIDErrorCodeOAuthAuthorization enum values.
+        \NSError_userInfo dictionary using the @c ::OIDOAuthErrorResponseErrorKey key.
+        The \NSError_code will be one of the @c ::OIDErrorCodeOAuthAuthorization enum values.
     @see https://tools.ietf.org/html/rfc6749#section-4.1.2.1
  */
 extern NSString *const OIDOAuthAuthorizationErrorDomain;
@@ -41,11 +41,11 @@ extern NSString *const OIDOAuthAuthorizationErrorDomain;
     @discussion This error domain is used when the server responds with HTTP 400 and an OAuth error,
         as defined RFC6749 Section 5.2. If an HTTP 400 response does not parse as an OAuth error
         (i.e. no 'error' field is present or the JSON is invalid), another error domain will be
-        used. The entire OAuth error response dictionary is available in the @c NSError.userInfo
+        used. The entire OAuth error response dictionary is available in the \NSError_userInfo
         dictionary using the @c ::OIDOAuthErrorResponseErrorKey key. Unlike transient network
         errors, errors in this domain invalidate the authentication state, and either indicate a
         client error or require user interaction (i.e. reauthentication) to resolve.
-        The @c NSError.code will be one of the @c ::OIDErrorCodeOAuthToken enum values.
+        The \NSError_code will be one of the @c ::OIDErrorCodeOAuthToken enum values.
     @see https://tools.ietf.org/html/rfc6749#section-5.2
  */
 extern NSString *const OIDOAuthTokenErrorDomain;
@@ -195,7 +195,7 @@ typedef NS_ENUM(NSInteger, OIDErrorCodeOAuth) {
   /*! @brief An OAuth error not known to this library
       @discussion Indicates an OAuth error as per RFC6749, but the error code was not in our
           list. It could be a custom error code, or one from an OAuth extension. See the "error" key
-          of the @c NSError:userInfo property. Such errors are assumed to invalidate the
+          of the \NSError_userInfo property. Such errors are assumed to invalidate the
           authentication state
    */
   OIDErrorCodeOAuthOther = -0xF000,
@@ -253,7 +253,7 @@ typedef NS_ENUM(NSInteger, OIDErrorCodeOAuthAuthorization) {
   /*! @brief An authorization OAuth error not known to this library
       @discussion this indicates an OAuth error as per RFC6749, but the error code was not in our
           list. It could be a custom error code, or one from an OAuth extension. See the "error" key
-          of the @c NSError:userInfo property. We assume such errors are not transient.
+          of the \NSError_userInfo property. We assume such errors are not transient.
       @see https://tools.ietf.org/html/rfc6749#section-4.1.2.1
    */
   OIDErrorCodeOAuthAuthorizationOther = OIDErrorCodeOAuthOther,
@@ -301,7 +301,7 @@ typedef NS_ENUM(NSInteger, OIDErrorCodeOAuthToken) {
   /*! @brief A token endpoint OAuth error not known to this library
       @discussion this indicates an OAuth error as per RFC6749, but the error code was not in our
           list. It could be a custom error code, or one from an OAuth extension. See the "error" key
-          of the @c NSError:userInfo property. We assume such errors are not transient.
+          of the \NSError_userInfo property. We assume such errors are not transient.
       @see https://tools.ietf.org/html/rfc6749#section-5.2
    */
   OIDErrorCodeOAuthTokenOther = OIDErrorCodeOAuthOther,

diff --git a/Source/OIDErrorUtilities.h b/Source/OIDErrorUtilities.h
@@ -23,57 +23,57 @@
 NS_ASSUME_NONNULL_BEGIN
 
 /*! @class OIDErrorUtilities
-    @brief Convenience methods for creating standardized @c NSError instances.
+    @brief Convenience methods for creating standardized \NSError instances.
  */
 @interface OIDErrorUtilities : NSObject
 
 /*! @fn errorWithCode:underlyingError:description:
-    @brief Creates a standard @c NSError from an @c ::OIDErrorCode and custom user info.
+    @brief Creates a standard \NSError from an @c ::OIDErrorCode and custom user info.
         Automatically populates the localized error description.
     @param code The error code.
     @param underlyingError The underlying error which occurred, if applicable.
     @param description A custom description, if applicable.
-    @return An @c NSError representing the error code.
+    @return An \NSError representing the error code.
  */
 + (nullable NSError *)errorWithCode:(OIDErrorCode)code
                     underlyingError:(nullable NSError *)underlyingError
                         description:(nullable NSString *)description;
 
 /*! @fn OAuthErrorWithDomain:OAuthResponse:underlyingError:
-    @brief Creates a standard @c NSError from an @c ::OIDErrorCode and custom user info.
+    @brief Creates a standard \NSError from an @c ::OIDErrorCode and custom user info.
         Automatically populates the localized error description.
     @param OAuthErrorDomain The OAuth error domain. Must be @c ::OIDOAuthAuthorizationErrorDomain or
         @c ::OIDOAuthTokenErrorDomain.
     @param errorResponse The dictionary from an OAuth error response (as per RFC6749 Section 5.2).
     @param underlyingError The underlying error which occurred, if applicable.
-    @return An @c NSError representing the OAuth error.
+    @return An \NSError representing the OAuth error.
     @see https://tools.ietf.org/html/rfc6749#section-5.2
  */
 + (nullable NSError *)OAuthErrorWithDomain:(NSString *)OAuthErrorDomain
                              OAuthResponse:(NSDictionary *)errorResponse
                            underlyingError:(nullable NSError *)underlyingError;
 
 /*! @fn resourceServerAuthorizationErrorWithCode:errorResponse:underlyingError:
-    @brief Creates a @c NSError indicating that the resource server responded with an authorization
+    @brief Creates a \NSError indicating that the resource server responded with an authorization
         error.
     @param code Your error code.
     @param errorResponse The resource server error response, if any.
     @param underlyingError The underlying error which occurred, if applicable.
-    @return An @c NSError representing the authorization error from the resource server.
+    @return An \NSError representing the authorization error from the resource server.
  */
 + (nullable NSError *)resourceServerAuthorizationErrorWithCode:(NSInteger)code
                                                 errorResponse:(nullable NSDictionary *)errorResponse
                                               underlyingError:(nullable NSError *)underlyingError;
 
 
 /*! @fn HTTPErrorWithHTTPResponse:data:
-    @brief Creates a standard @c NSError from an @c NSHTTPURLResponse. Automatically
+    @brief Creates a standard \NSError from an \NSHTTPURLResponse. Automatically
         populates the localized error description with the response data associated with the
-        @c NSHTTPURLResponse, if available.
+        \NSHTTPURLResponse, if available.
     @param HTTPURLResponse The response which indicates an error occurred.
     @param data The response data associated with the response which should be converted to an
         @c NSString assuming a UTF-8 encoding, if available.
-    @return An @c NSError representing the error.
+    @return An \NSError representing the error.
  */
 + (nullable NSError *)HTTPErrorWithHTTPResponse:(NSHTTPURLResponse *)HTTPURLResponse
                                            data:(nullable NSData *)data;