diff --git a/ParseTwitterUtils/Internal/Dialog/PFOAuth1FlowDialog.h b/ParseTwitterUtils/Internal/Dialog/PFOAuth1FlowDialog.h index e8e6354..9adc38c 100644 --- a/ParseTwitterUtils/Internal/Dialog/PFOAuth1FlowDialog.h +++ b/ParseTwitterUtils/Internal/Dialog/PFOAuth1FlowDialog.h @@ -14,7 +14,7 @@ @protocol PFOAuth1FlowDialogDataSource -/*! +/** Asks if a link touched by a user should be opened in an external browser. If a user touches a link, the default behavior is to open the link in the Safari browser, @@ -30,7 +30,7 @@ typedef void (^PFOAuth1FlowDialogCompletion)(BOOL succeeded, NSURL *url, NSError *error); -/*! +/** To allow for greater mockability, this protocol exposes all of the methods implemented by PFOAuth1FlowDialog. */ @protocol PFOAuth1FlowDialogInterface @@ -41,25 +41,25 @@ typedef void (^PFOAuth1FlowDialogCompletion)(BOOL succeeded, NSURL *url, NSError @property (nonatomic, copy) NSDictionary *queryParameters; @property (nonatomic, copy) NSString *redirectURLPrefix; -/*! +/** The title that is shown in the header atop the view. */ @property (nonatomic, copy) NSString *title; + (instancetype)dialogWithURL:(NSURL *)url queryParameters:(NSDictionary *)queryParameters; -/*! +/** The view will be added to the top of the current key window. */ - (void)showAnimated:(BOOL)animated; -/*! +/** Hides the view. This method does not call the completion block. */ - (void)dismissAnimated:(BOOL)animated; -/*! +/** Displays a URL in the dialog. */ - (void)loadURL:(NSURL *)url queryParameters:(NSDictionary *)parameters; diff --git a/ParseTwitterUtils/Internal/PFTwitterPrivateUtilities.h b/ParseTwitterUtils/Internal/PFTwitterPrivateUtilities.h index 62c02ae..f556d2b 100644 --- a/ParseTwitterUtils/Internal/PFTwitterPrivateUtilities.h +++ b/ParseTwitterUtils/Internal/PFTwitterPrivateUtilities.h @@ -32,7 +32,7 @@ @end -/*! +/** Raises an `NSInternalInconsistencyException` if the `condition` does not pass. Use `description` to supply the way to fix the exception. */ diff --git a/ParseTwitterUtils/Internal/PF_Twitter_Private.h b/ParseTwitterUtils/Internal/PF_Twitter_Private.h index f714c05..2d69c55 100644 --- a/ParseTwitterUtils/Internal/PF_Twitter_Private.h +++ b/ParseTwitterUtils/Internal/PF_Twitter_Private.h @@ -27,7 +27,7 @@ NS_ASSUME_NONNULL_BEGIN urlSession:(NSURLSession *)urlSession dialogClass:(Class)dialogClass; -/*! +/** Obtain access to the local twitter account. Returns the twitter account if access is obtained. Otherwise, returns null. */ diff --git a/ParseTwitterUtils/PFTwitterUtils.h b/ParseTwitterUtils/PFTwitterUtils.h index 99ccca5..adf42f1 100644 --- a/ParseTwitterUtils/PFTwitterUtils.h +++ b/ParseTwitterUtils/PFTwitterUtils.h @@ -17,7 +17,7 @@ NS_ASSUME_NONNULL_BEGIN @class BFTask PF_GENERIC(__covariant BFGenericType); @class PF_Twitter; -/*! +/** The `PFTwitterUtils` class provides utility functions for working with Twitter in a Parse application. This class is currently for iOS only. @@ -28,15 +28,15 @@ NS_ASSUME_NONNULL_BEGIN /// @name Interacting With Twitter ///-------------------------------------- -/*! - @abstract Gets the instance of the object that Parse uses. +/** + Gets the instance of the `PF_Twitter` object that Parse uses. - @returns An instance of object. + @return An instance of `PF_Twitter` object. */ + (nullable PF_Twitter *)twitter; -/*! - @abstract Initializes the Twitter singleton. +/** + Initializes the Twitter singleton. @warning You must invoke this in order to use the Twitter functionality in Parse. @@ -45,12 +45,12 @@ NS_ASSUME_NONNULL_BEGIN */ + (void)initializeWithConsumerKey:(NSString *)consumerKey consumerSecret:(NSString *)consumerSecret; -/*! - @abstract Whether the user has their account linked to Twitter. +/** + Whether the user has their account linked to Twitter. @param user User to check for a Twitter link. The user must be logged in on this device. - @returns `YES` if the user has their account linked to Twitter, otherwise `NO`. + @return `YES` if the user has their account linked to Twitter, otherwise `NO`. */ + (BOOL)isLinkedWithUser:(nullable PFUser *)user; @@ -58,21 +58,21 @@ NS_ASSUME_NONNULL_BEGIN /// @name Logging In & Creating Twitter-Linked Users ///-------------------------------------- -/*! - @abstract *Asynchronously* logs in a user using Twitter. +/** + *Asynchronously* logs in a user using Twitter. - @discussion This method delegates to Twitter to authenticate the user, - and then automatically logs in (or creates, in the case where it is a new user) a . + This method delegates to Twitter to authenticate the user, + and then automatically logs in (or creates, in the case where it is a new user) a `PFUser`. - @returns The task, that encapsulates the work being done. + @return The task, that encapsulates the work being done. */ + (BFTask PF_GENERIC(PFUser *)*)logInInBackground; -/*! - @abstract *Asynchronously* logs in a user using Twitter. +/** + *Asynchronously* logs in a user using Twitter. - @discussion This method delegates to Twitter to authenticate the user, - and then automatically logs in (or creates, in the case where it is a new user) . + This method delegates to Twitter to authenticate the user, + and then automatically logs in (or creates, in the case where it is a new user) `PFUser`. @param block The block to execute. It should have the following argument signature: `^(PFUser *user, NSError *error)`. @@ -80,10 +80,10 @@ NS_ASSUME_NONNULL_BEGIN + (void)logInWithBlock:(nullable PFUserResultBlock)block; /* - @abstract *Asynchronously* Logs in a user using Twitter. + *Asynchronously* Logs in a user using Twitter. - @discussion This method delegates to Twitter to authenticate the user, - and then automatically logs in (or creates, in the case where it is a new user) a . + This method delegates to Twitter to authenticate the user, + and then automatically logs in (or creates, in the case where it is a new user) a `PFUser`. @param target Target object for the selector @param selector The selector that will be called when the asynchrounous request is complete. @@ -91,29 +91,29 @@ NS_ASSUME_NONNULL_BEGIN */ + (void)logInWithTarget:(nullable id)target selector:(nullable SEL)selector; -/*! - @abstract *Asynchronously* logs in a user using Twitter. +/** + *Asynchronously* logs in a user using Twitter. - @discussion Allows you to handle user login to Twitter, then provide authentication - data to log in (or create, in the case where it is a new user) the . + Allows you to handle user login to Twitter, then provide authentication + data to log in (or create, in the case where it is a new user) the `PFUser`. @param twitterId The id of the Twitter user being linked. @param screenName The screen name of the Twitter user being linked. @param authToken The auth token for the user's session. @param authTokenSecret The auth token secret for the user's session. - @returns The task, that encapsulates the work being done. + @return The task, that encapsulates the work being done. */ + (BFTask PF_GENERIC(PFUser *)*)logInWithTwitterIdInBackground:(NSString *)twitterId screenName:(NSString *)screenName authToken:(NSString *)authToken authTokenSecret:(NSString *)authTokenSecret; -/*! - @abstract Logs in a user using Twitter. +/** + Logs in a user using Twitter. - @discussion Allows you to handle user login to Twitter, then provide authentication data - to log in (or create, in the case where it is a new user) the . + Allows you to handle user login to Twitter, then provide authentication data + to log in (or create, in the case where it is a new user) the `PFUser`. @param twitterId The id of the Twitter user being linked @param screenName The screen name of the Twitter user being linked @@ -129,10 +129,10 @@ NS_ASSUME_NONNULL_BEGIN block:(nullable PFUserResultBlock)block; /* - @abstract Logs in a user using Twitter. + Logs in a user using Twitter. - @discussion Allows you to handle user login to Twitter, then provide authentication data - to log in (or create, in the case where it is a new user) the . + Allows you to handle user login to Twitter, then provide authentication data + to log in (or create, in the case where it is a new user) the `PFUser`. @param twitterId The id of the Twitter user being linked. @param screenName The screen name of the Twitter user being linked. @@ -153,11 +153,11 @@ NS_ASSUME_NONNULL_BEGIN /// @name Linking Users with Twitter ///-------------------------------------- -/*! - @abstract *Asynchronously* links Twitter to an existing PFUser. +/** + *Asynchronously* links Twitter to an existing PFUser. - @discussion This method delegates to Twitter to authenticate the user, - and then automatically links the account to the . + This method delegates to Twitter to authenticate the user, + and then automatically links the account to the `PFUser`. @param user User to link to Twitter. @@ -165,23 +165,23 @@ NS_ASSUME_NONNULL_BEGIN */ + (void)linkUser:(PFUser *)user PARSE_DEPRECATED("Please use +linkUserInBackground: instead."); -/*! - @abstract *Asynchronously* links Twitter to an existing . +/** + *Asynchronously* links Twitter to an existing `PFUser`. - @discussion This method delegates to Twitter to authenticate the user, - and then automatically links the account to the . + This method delegates to Twitter to authenticate the user, + and then automatically links the account to the `PFUser`. @param user User to link to Twitter. - @returns The task, that encapsulates the work being done. + @return The task, that encapsulates the work being done. */ + (BFTask PF_GENERIC(NSNumber *)*)linkUserInBackground:(PFUser *)user; -/*! - @abstract *Asynchronously* links Twitter to an existing . +/** + *Asynchronously* links Twitter to an existing `PFUser`. - @discussion This method delegates to Twitter to authenticate the user, - and then automatically links the account to the . + This method delegates to Twitter to authenticate the user, + and then automatically links the account to the `PFUser`. @param user User to link to Twitter. @param block The block to execute. @@ -190,10 +190,10 @@ NS_ASSUME_NONNULL_BEGIN + (void)linkUser:(PFUser *)user block:(nullable PFBooleanResultBlock)block; /* - @abstract *Asynchronously* links Twitter to an existing . + *Asynchronously* links Twitter to an existing `PFUser`. - @discussion This method delegates to Twitter to authenticate the user, - and then automatically links the account to the . + This method delegates to Twitter to authenticate the user, + and then automatically links the account to the `PFUser`. @param user User to link to Twitter. @param target Target object for the selector @@ -202,18 +202,18 @@ NS_ASSUME_NONNULL_BEGIN */ + (void)linkUser:(PFUser *)user target:(nullable id)target selector:(nullable SEL)selector; -/*! - @abstract *Asynchronously* links Twitter to an existing PFUser asynchronously. +/** + *Asynchronously* links Twitter to an existing PFUser asynchronously. - @discussion Allows you to handle user login to Twitter, - then provide authentication data to link the account to the . + Allows you to handle user login to Twitter, + then provide authentication data to link the account to the `PFUser`. @param user User to link to Twitter. @param twitterId The id of the Twitter user being linked. @param screenName The screen name of the Twitter user being linked. @param authToken The auth token for the user's session. @param authTokenSecret The auth token secret for the user's session. - @returns The task, that encapsulates the work being done. + @return The task, that encapsulates the work being done. */ + (BFTask PF_GENERIC(NSNumber *)*)linkUserInBackground:(PFUser *)user twitterId:(NSString *)twitterId @@ -221,11 +221,11 @@ NS_ASSUME_NONNULL_BEGIN authToken:(NSString *)authToken authTokenSecret:(NSString *)authTokenSecret; -/*! - @abstract *Asynchronously* links Twitter to an existing . +/** + *Asynchronously* links Twitter to an existing `PFUser`. @discussionAllows you to handle user login to Twitter, - then provide authentication data to link the account to the . + then provide authentication data to link the account to the `PFUser`. @param user User to link to Twitter. @param twitterId The id of the Twitter user being linked. @@ -243,10 +243,10 @@ NS_ASSUME_NONNULL_BEGIN block:(nullable PFBooleanResultBlock)block; /* - @abstract Links Twitter to an existing . + Links Twitter to an existing `PFUser`. - @discussion This method allows you to handle user login to Twitter, - then provide authentication data to link the account to the . + This method allows you to handle user login to Twitter, + then provide authentication data to link the account to the `PFUser`. @param user User to link to Twitter. @param twitterId The id of the Twitter user being linked. @@ -269,36 +269,36 @@ NS_ASSUME_NONNULL_BEGIN /// @name Unlinking Users from Twitter ///-------------------------------------- -/*! - @abstract *Synchronously* unlinks the from a Twitter account. +/** + *Synchronously* unlinks the `PFUser` from a Twitter account. @param user User to unlink from Twitter. - @returns Returns true if the unlink was successful. + @return Returns true if the unlink was successful. */ + (BOOL)unlinkUser:(PFUser *)user; -/*! - @abstract *Synchronously* unlinks the PFUser from a Twitter account. +/** + *Synchronously* unlinks the PFUser from a Twitter account. @param user User to unlink from Twitter. @param error Error object to set on error. - @returns Returns `YES` if the unlink was successful, otherwise `NO`. + @return Returns `YES` if the unlink was successful, otherwise `NO`. */ + (BOOL)unlinkUser:(PFUser *)user error:(NSError **)error; -/*! - @abstract Makes an *asynchronous* request to unlink a user from a Twitter account. +/** + Makes an *asynchronous* request to unlink a user from a Twitter account. @param user User to unlink from Twitter. - @returns The task, that encapsulates the work being done. + @return The task, that encapsulates the work being done. */ + (BFTask PF_GENERIC(NSNumber *)*)unlinkUserInBackground:(PFUser *)user; -/*! - @abstract Makes an *asynchronous* request to unlink a user from a Twitter account. +/** + Makes an *asynchronous* request to unlink a user from a Twitter account. @param user User to unlink from Twitter. @param block The block to execute. @@ -307,7 +307,7 @@ NS_ASSUME_NONNULL_BEGIN + (void)unlinkUserInBackground:(PFUser *)user block:(nullable PFBooleanResultBlock)block; /* - @abstract Makes an *asynchronous* request to unlink a user from a Twitter account. + Makes an *asynchronous* request to unlink a user from a Twitter account. @param user User to unlink from Twitter @param target Target object for the selector diff --git a/ParseTwitterUtils/PF_Twitter.h b/ParseTwitterUtils/PF_Twitter.h index a2f0a10..bc0785a 100644 --- a/ParseTwitterUtils/PF_Twitter.h +++ b/ParseTwitterUtils/PF_Twitter.h @@ -15,52 +15,52 @@ NS_ASSUME_NONNULL_BEGIN @class BFTask PF_GENERIC(__covariant BFGenericType); -/*! +/** The `PF_Twitter` class is a simple interface for interacting with the Twitter REST API, automating sign-in and OAuth signing of requests against the API. */ @interface PF_Twitter : NSObject -/*! - @abstract Consumer key of the application that is used to authorize with Twitter. +/** + Consumer key of the application that is used to authorize with Twitter. */ @property (nullable, nonatomic, copy) NSString *consumerKey; -/*! - @abstract Consumer secret of the application that is used to authorize with Twitter. +/** + Consumer secret of the application that is used to authorize with Twitter. */ @property (nullable, nonatomic, copy) NSString *consumerSecret; -/*! - @abstract Auth token for the current user. +/** + Auth token for the current user. */ @property (nullable, nonatomic, copy) NSString *authToken; -/*! - @abstract Auth token secret for the current user. +/** + Auth token secret for the current user. */ @property (nullable, nonatomic, copy) NSString *authTokenSecret; -/*! - @abstract Twitter user id of the currently signed in user. +/** + Twitter user id of the currently signed in user. */ @property (nullable, nonatomic, copy) NSString *userId; -/*! - @abstract Twitter screen name of the currently signed in user. +/** + Twitter screen name of the currently signed in user. */ @property (nullable, nonatomic, copy) NSString *screenName; -/*! - @abstract Displays an auth dialog and populates the authToken, authTokenSecret, userId, and screenName properties +/** + Displays an auth dialog and populates the authToken, authTokenSecret, userId, and screenName properties if the Twitter user grants permission to the application. - @returns The task, that encapsulates the work being done. + @return The task, that encapsulates the work being done. */ - (BFTask *)authorizeInBackground; -/*! - @abstract Displays an auth dialog and populates the authToken, authTokenSecret, userId, and screenName properties +/** + Displays an auth dialog and populates the authToken, authTokenSecret, userId, and screenName properties if the Twitter user grants permission to the application. @param success Invoked upon successful authorization. @@ -71,11 +71,11 @@ NS_ASSUME_NONNULL_BEGIN failure:(nullable void (^)(NSError *__nullable error))failure cancel:(nullable void (^)(void))cancel; -/*! - @abstract Adds a 3-legged OAuth signature to an `NSMutableURLRequest` based +/** + Adds a 3-legged OAuth signature to an `NSMutableURLRequest` based upon the properties set for the Twitter object. - @discussion Use this function to sign requests being made to the Twitter API. + Use this function to sign requests being made to the Twitter API. @param request Request to sign. */ diff --git a/ParseTwitterUtils/PF_Twitter.m b/ParseTwitterUtils/PF_Twitter.m index 75c705d..4d2af46 100644 --- a/ParseTwitterUtils/PF_Twitter.m +++ b/ParseTwitterUtils/PF_Twitter.m @@ -153,7 +153,7 @@ - (BFTask *)_showWebViewDialogAsync:(NSString *)requestToken requestSecret:(NSSt return source.task; } -/*! +/** Get the request token for the authentication. This is the first step in auth. if isReverseAuth is YES then get the request token for reverse auth mode. Otherwise, get the request token for web auth mode. */ @@ -227,7 +227,7 @@ - (BFTask *)_getAccessTokenForWebAuthAsync:(NSString *)verifier return taskCompletionSource.task; } -/*! +/** Get the access token for reverse authentication. If the Task is successful then, Task result is dictionary containing logged in user's Auth token, Screenname and other attributes. */ diff --git a/Tests/Other/PFTwitterTestMacros.h b/Tests/Other/PFTwitterTestMacros.h index 737f4a7..5c1461e 100644 --- a/Tests/Other/PFTwitterTestMacros.h +++ b/Tests/Other/PFTwitterTestMacros.h @@ -10,7 +10,7 @@ #ifndef PFTwitterTestMacros_h #define PFTwitterTestMacros_h -/*! +/** To prevent retain cycles by OCMock, this macro allows us to capture a weak reference to return from a stubbed method. */ #define andReturnWeak(variable) _andDo( \