Merge pull request #22 from ParsePlatform/nlutsenko.docs

Update all of the public documentation to new style.

Author: nlutsenko

ParseFacebookUtils/PFFacebookUtils.h

@@ -20,8 +20,8 @@
 
 NS_ASSUME_NONNULL_BEGIN
 
-/*!
- The `PFFacebookUtils` class provides utility functions for using Facebook authentication with <PFUser>s.
+/**
+ The `PFFacebookUtils` class provides utility functions for using Facebook authentication with `PFUser`s.
 
  @warning This class supports official Facebook iOS SDK v4.0+ and is available only on iOS.
  */
@@ -31,10 +31,10 @@ NS_ASSUME_NONNULL_BEGIN
 /// @name Interacting With Facebook
 ///--------------------------------------
 
-/*!
- @abstract Initializes Parse Facebook Utils.
+/**
+ Initializes Parse Facebook Utils.
 
- @discussion You must provide your Facebook application ID as the value for FacebookAppID in your bundle's plist file
+ You must provide your Facebook application ID as the value for FacebookAppID in your bundle's plist file
  as described here: https://developers.facebook.com/docs/getting-started/facebook-sdk-for-ios/
 
  @warning You must invoke this in order to use the Facebook functionality in Parse.
@@ -43,35 +43,35 @@ NS_ASSUME_NONNULL_BEGIN
  */
 + (void)initializeFacebookWithApplicationLaunchOptions:(nullable NSDictionary *)launchOptions;
 
-/*!
- @abstract `FBSDKLoginManager` provides methods for configuring login behavior, default audience
+/**
+ `FBSDKLoginManager` provides methods for configuring login behavior, default audience
  and managing Facebook Access Token.
 
- @returns An instance of `FBSDKLoginManager` that is used by `PFFacebookUtils`.
+ @return An instance of `FBSDKLoginManager` that is used by `PFFacebookUtils`.
  */
 + (FBSDKLoginManager *)facebookLoginManager;
 
 ///--------------------------------------
 /// @name Logging In
 ///--------------------------------------
 
-/*!
- @abstract *Asynchronously* logs in a user using Facebook with read permissions.
+/**
+ *Asynchronously* logs in a user using Facebook with read permissions.
 
- @discussion This method delegates to the Facebook SDK to authenticate the user,
- and then automatically logs in (or creates, in the case where it is a new user) a <PFUser>.
+ This method delegates to the Facebook SDK to authenticate the user,
+ and then automatically logs in (or creates, in the case where it is a new user) a `PFUser`.
 
  @param permissions Array of read permissions to use.
 
- @returns The task that has will a have `result` set to <PFUser> if operation succeeds.
+ @return The task that has will a have `result` set to `PFUser` if operation succeeds.
  */
 + (BFTask PF_GENERIC(PFUser *)*)logInInBackgroundWithReadPermissions:(nullable NSArray PF_GENERIC(NSString *)*)permissions;
 
-/*!
- @abstract *Asynchronously* logs in a user using Facebook with read permissions.
+/**
+ *Asynchronously* logs in a user using Facebook with read permissions.
 
- @discussion This method delegates to the Facebook SDK to authenticate the user,
- and then automatically logs in (or creates, in the case where it is a new user) a <PFUser>.
+ This method delegates to the Facebook SDK to authenticate the user,
+ and then automatically logs in (or creates, in the case where it is a new user) a `PFUser`.
 
  @param permissions Array of read permissions to use.
  @param block       The block to execute when the log in completes.
@@ -80,23 +80,23 @@ NS_ASSUME_NONNULL_BEGIN
 + (void)logInInBackgroundWithReadPermissions:(nullable NSArray PF_GENERIC(NSString *)*)permissions
                                        block:(nullable PFUserResultBlock)block;
 
-/*!
- @abstract *Asynchronously* logs in a user using Facebook with publish permissions.
+/**
+ *Asynchronously* logs in a user using Facebook with publish permissions.
 
- @discussion This method delegates to the Facebook SDK to authenticate the user,
- and then automatically logs in (or creates, in the case where it is a new user) a <PFUser>.
+ This method delegates to the Facebook SDK to authenticate the user,
+ and then automatically logs in (or creates, in the case where it is a new user) a `PFUser`.
 
  @param permissions Array of publish permissions to use.
 
- @returns The task that has will a have `result` set to <PFUser> if operation succeeds.
+ @return The task that has will a have `result` set to `PFUser` if operation succeeds.
  */
 + (BFTask PF_GENERIC(PFUser *)*)logInInBackgroundWithPublishPermissions:(nullable NSArray PF_GENERIC(NSString *)*)permissions;
 
-/*!
- @abstract *Asynchronously* logs in a user using Facebook with publish permissions.
+/**
+ *Asynchronously* logs in a user using Facebook with publish permissions.
 
- @discussion This method delegates to the Facebook SDK to authenticate the user,
- and then automatically logs in (or creates, in the case where it is a new user) a <PFUser>.
+ This method delegates to the Facebook SDK to authenticate the user,
+ and then automatically logs in (or creates, in the case where it is a new user) a `PFUser`.
 
  @param permissions Array of publish permissions to use.
  @param block       The block to execute when the log in completes.
@@ -105,23 +105,23 @@ NS_ASSUME_NONNULL_BEGIN
 + (void)logInInBackgroundWithPublishPermissions:(nullable NSArray PF_GENERIC(NSString *)*)permissions
                                           block:(nullable PFUserResultBlock)block;
 
-/*!
- @abstract *Asynchronously* logs in a user using given Facebook Acess Token.
+/**
+ *Asynchronously* logs in a user using given Facebook Acess Token.
 
- @discussion This method delegates to the Facebook SDK to authenticate the user,
- and then automatically logs in (or creates, in the case where it is a new user) a <PFUser>.
+ This method delegates to the Facebook SDK to authenticate the user,
+ and then automatically logs in (or creates, in the case where it is a new user) a `PFUser`.
 
  @param accessToken An instance of `FBSDKAccessToken` to use when logging in.
 
- @returns The task that has will a have `result` set to <PFUser> if operation succeeds.
+ @return The task that has will a have `result` set to `PFUser` if operation succeeds.
  */
 + (BFTask PF_GENERIC(PFUser *)*)logInInBackgroundWithAccessToken:(FBSDKAccessToken *)accessToken;
 
-/*!
- @abstract *Asynchronously* logs in a user using given Facebook Acess Token.
+/**
+ *Asynchronously* logs in a user using given Facebook Acess Token.
 
- @discussion This method delegates to the Facebook SDK to authenticate the user,
- and then automatically logs in (or creates, in the case where it is a new user) a <PFUser>.
+ This method delegates to the Facebook SDK to authenticate the user,
+ and then automatically logs in (or creates, in the case where it is a new user) a `PFUser`.
 
  @param accessToken An instance of `FBSDKAccessToken` to use when logging in.
  @param block       The block to execute when the log in completes.
@@ -134,26 +134,26 @@ NS_ASSUME_NONNULL_BEGIN
 /// @name Linking Users
 ///--------------------------------------
 
-/*!
- @abstract *Asynchronously* links Facebook with read permissions to an existing <PFUser>.
+/**
+ *Asynchronously* links Facebook with read permissions to an existing `PFUser`.
 
- @discussion This method delegates to the Facebook SDK to authenticate
- the user, and then automatically links the account to the <PFUser>.
+ This method delegates to the Facebook SDK to authenticate
+ the user, and then automatically links the account to the `PFUser`.
  It will also save any unsaved changes that were made to the `user`.
 
  @param user        User to link to Facebook.
  @param permissions Array of read permissions to use when logging in with Facebook.
 
- @returns The task that will have a `result` set to `@YES` if operation succeeds.
+ @return The task that will have a `result` set to `@YES` if operation succeeds.
  */
 + (BFTask PF_GENERIC(NSNumber *)*)linkUserInBackground:(PFUser *)user
                                    withReadPermissions:(nullable NSArray PF_GENERIC(NSString *)*)permissions;
 
-/*!
- @abstract *Asynchronously* links Facebook with read permissions to an existing <PFUser>.
+/**
+ *Asynchronously* links Facebook with read permissions to an existing `PFUser`.
 
- @discussion This method delegates to the Facebook SDK to authenticate
- the user, and then automatically links the account to the <PFUser>.
+ This method delegates to the Facebook SDK to authenticate
+ the user, and then automatically links the account to the `PFUser`.
  It will also save any unsaved changes that were made to the `user`.
 
  @param user        User to link to Facebook.
@@ -165,26 +165,26 @@ NS_ASSUME_NONNULL_BEGIN
          withReadPermissions:(nullable NSArray PF_GENERIC(NSString *)*)permissions
                        block:(nullable PFBooleanResultBlock)block;
 
-/*!
- @abstract *Asynchronously* links Facebook with publish permissions to an existing <PFUser>.
+/**
+ *Asynchronously* links Facebook with publish permissions to an existing `PFUser`.
 
- @discussion This method delegates to the Facebook SDK to authenticate
- the user, and then automatically links the account to the <PFUser>.
+ This method delegates to the Facebook SDK to authenticate
+ the user, and then automatically links the account to the `PFUser`.
  It will also save any unsaved changes that were made to the `user`.
 
  @param user        User to link to Facebook.
  @param permissions Array of publish permissions to use.
 
- @returns The task that will have a `result` set to `@YES` if operation succeeds.
+ @return The task that will have a `result` set to `@YES` if operation succeeds.
  */
 + (BFTask PF_GENERIC(NSNumber *)*)linkUserInBackground:(PFUser *)user
                                 withPublishPermissions:(NSArray PF_GENERIC(NSString *)*)permissions;
 
-/*!
- @abstract *Asynchronously* links Facebook with publish permissions to an existing <PFUser>.
+/**
+ *Asynchronously* links Facebook with publish permissions to an existing `PFUser`.
 
- @discussion This method delegates to the Facebook SDK to authenticate
- the user, and then automatically links the account to the <PFUser>.
+ This method delegates to the Facebook SDK to authenticate
+ the user, and then automatically links the account to the `PFUser`.
  It will also save any unsaved changes that were made to the `user`.
 
  @param user        User to link to Facebook.
@@ -196,25 +196,25 @@ NS_ASSUME_NONNULL_BEGIN
       withPublishPermissions:(NSArray PF_GENERIC(NSString *)*)permissions
                        block:(nullable PFBooleanResultBlock)block;
 
-/*!
- @abstract *Asynchronously* links Facebook Access Token to an existing <PFUser>.
+/**
+ *Asynchronously* links Facebook Access Token to an existing `PFUser`.
 
- @discussion This method delegates to the Facebook SDK to authenticate
- the user, and then automatically links the account to the <PFUser>.
+ This method delegates to the Facebook SDK to authenticate
+ the user, and then automatically links the account to the `PFUser`.
  It will also save any unsaved changes that were made to the `user`.
 
  @param user        User to link to Facebook.
  @param accessToken An instance of `FBSDKAccessToken` to use.
 
- @returns The task that will have a `result` set to `@YES` if operation succeeds.
+ @return The task that will have a `result` set to `@YES` if operation succeeds.
  */
 + (BFTask PF_GENERIC(NSNumber *)*)linkUserInBackground:(PFUser *)user withAccessToken:(FBSDKAccessToken *)accessToken;
 
-/*!
- @abstract *Asynchronously* links Facebook Access Token to an existing <PFUser>.
+/**
+ *Asynchronously* links Facebook Access Token to an existing `PFUser`.
 
- @discussion This method delegates to the Facebook SDK to authenticate
- the user, and then automatically links the account to the <PFUser>.
+ This method delegates to the Facebook SDK to authenticate
+ the user, and then automatically links the account to the `PFUser`.
  It will also save any unsaved changes that were made to the `user`.
 
  @param user        User to link to Facebook.
@@ -230,16 +230,16 @@ NS_ASSUME_NONNULL_BEGIN
 /// @name Unlinking Users
 ///--------------------------------------
 
-/*!
- @abstract Unlinks the <PFUser> from a Facebook account *asynchronously*.
+/**
+ Unlinks the `PFUser` from a Facebook account *asynchronously*.
 
  @param user User to unlink from Facebook.
- @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 Unlinks the <PFUser> from a Facebook account *asynchronously*.
+/**
+ Unlinks the `PFUser` from a Facebook account *asynchronously*.
 
  @param user User to unlink from Facebook.
  @param block The block to execute.
@@ -251,12 +251,12 @@ NS_ASSUME_NONNULL_BEGIN
 /// @name Getting Linked State
 ///--------------------------------------
 
-/*!
- @abstract Whether the user has their account linked to Facebook.
+/**
+ Whether the user has their account linked to Facebook.
 
  @param user User to check for a facebook link. The user must be logged in on this device.
 
- @returns `YES` if the user has their account linked to Facebook, otherwise `NO`.
+ @return `YES` if the user has their account linked to Facebook, otherwise `NO`.
  */
 + (BOOL)isLinkedWithUser:(PFUser *)user;