Improve doc comments (#266)

Author: petea

GoogleSignIn/Sources/Public/GoogleSignIn/GIDGoogleUser.h

@@ -38,16 +38,16 @@
 
 NS_ASSUME_NONNULL_BEGIN
 
-/// This class represents a user account.
+/// This class represents a signed-in user.
 @interface GIDGoogleUser : NSObject <NSSecureCoding>
 
 /// The Google user ID.
 @property(nonatomic, readonly, nullable) NSString *userID;
 
-/// Representation of basic profile data for the user.
+/// The basic profile data for the user.
 @property(nonatomic, readonly, nullable) GIDProfileData *profile;
 
-/// The API scopes granted to the app in an array of `NSString`.
+/// The OAuth2 scopes granted to the app in an array of `NSString`.
 @property(nonatomic, readonly, nullable) NSArray<NSString *> *grantedScopes;
 
 /// The configuration that was used to sign in this user.
@@ -59,20 +59,19 @@ NS_ASSUME_NONNULL_BEGIN
 /// The OAuth2 refresh token to exchange for new access tokens.
 @property(nonatomic, readonly) GIDToken *refreshToken;
 
-/// An OpenID Connect ID token that identifies the user.
+/// The OpenID Connect ID token that identifies the user.
 ///
 /// Send this token to your server to authenticate the user there. For more information on this topic,
 /// see https://developers.google.com/identity/sign-in/ios/backend-auth.
 @property(nonatomic, readonly, nullable) GIDToken *idToken;
 
-/// The authorizer for `GTLService`, `GTMSessionFetcher`, or `GTMHTTPFetcher`.
 #pragma clang diagnostic push
 #pragma clang diagnostic ignored "-Wdeprecated-declarations"
+/// The authorizer for use with `GTLRService`, `GTMSessionFetcher`, or `GTMHTTPFetcher`.
 @property(nonatomic, readonly) id<GTMFetcherAuthorizationProtocol> fetcherAuthorizer;
 #pragma clang diagnostic pop
 
-/// Get a valid access token and a valid ID token, refreshing them first if they have expired or
-/// are about to expire.
+/// Refresh the user's access and ID tokens if they have expired or are about to expire.
 ///
 /// @param completion A completion block that takes a `GIDGoogleUser` or an error if the attempt to
 ///     refresh tokens was unsuccessful.  The block will be called asynchronously on the main queue.
@@ -81,7 +80,7 @@ NS_ASSUME_NONNULL_BEGIN
 
 #if TARGET_OS_IOS || TARGET_OS_MACCATALYST
 
-/// Starts an interactive consent flow on iOS to add scopes to the current user's grants.
+/// Starts an interactive consent flow on iOS to add new scopes to the user's `grantedScopes`.
 ///
 /// The completion will be called at the end of this process.  If successful, a `GIDUserAuth`
 /// instance will be returned reflecting the new scopes and saved sign-in state will be updated.
@@ -90,8 +89,8 @@ NS_ASSUME_NONNULL_BEGIN
 /// @param presentingViewController The view controller used to present `SFSafariViewContoller` on
 ///     iOS 9 and 10 and to supply `presentationContextProvider` for `ASWebAuthenticationSession` on
 ///     iOS 13+.
-/// @param completion The block that is called on completion.  This block will be called asynchronously
-///     on the main queue.
+/// @param completion The optional block that is called on completion.  This block will be called
+///     asynchronously on the main queue.
 - (void)addScopes:(NSArray<NSString *> *)scopes
     presentingViewController:(UIViewController *)presentingViewController
                   completion:(nullable void (^)(GIDUserAuth *_Nullable userAuth,
@@ -100,15 +99,16 @@ NS_ASSUME_NONNULL_BEGIN
 
 #elif TARGET_OS_OSX
 
-/// Starts an interactive consent flow on macOS to add scopes to the current user's grants.
+/// Starts an interactive consent flow on macOS to add new scopes to the user's `grantedScopes`.
 ///
 /// The completion will be called at the end of this process.  If successful, a `GIDUserAuth`
 /// instance will be returned reflecting the new scopes and saved sign-in state will be updated.
 ///
 /// @param scopes An array of scopes to ask the user to consent to.
-/// @param presentingWindow The window used to supply `presentationContextProvider` for `ASWebAuthenticationSession`.
-/// @param completion The block that is called on completion.  This block will be called asynchronously
-///     on the main queue.
+/// @param presentingWindow The window used to supply `presentationContextProvider` for
+///     `ASWebAuthenticationSession`.
+/// @param completion The optional block that is called on completion.  This block will be called
+///     asynchronously on the main queue.
 - (void)addScopes:(NSArray<NSString *> *)scopes
     presentingWindow:(NSWindow *)presentingWindow
           completion:(nullable void (^)(GIDUserAuth *_Nullable userAuth,

GoogleSignIn/Sources/Public/GoogleSignIn/GIDSignIn.h

@@ -51,13 +51,13 @@ typedef NS_ERROR_ENUM(kGIDSignInErrorDomain, GIDSignInErrorCode) {
   kGIDSignInErrorCodeMismatchWithCurrentUser = -9,
 };
 
-/// This class signs the user in with Google.
+/// This class is used to sign in users with their Google account and manage their session.
 ///
-/// For reference, please see "Google Sign-In for iOS" at
+/// For reference, please see "Google Sign-In for iOS and macOS" at
 /// https://developers.google.com/identity/sign-in/ios
 @interface GIDSignIn : NSObject
 
-/// A shared `GIDSignIn` instance.
+/// The shared `GIDSignIn` instance.
 @property(class, nonatomic, readonly) GIDSignIn *sharedInstance;
 
 /// The `GIDGoogleUser` object representing the current user or `nil` if there is no signed-in user.
@@ -81,29 +81,29 @@ typedef NS_ERROR_ENUM(kGIDSignInErrorDomain, GIDSignInErrorCode) {
 /// @return `YES` if `GIDSignIn` handled this URL.
 - (BOOL)handleURL:(NSURL *)url;
 
-/// Checks if there is a previously authenticated user saved in keychain.
+/// Checks if there is a previous user sign-in saved in keychain.
 ///
-/// @return `YES` if there is a previously authenticated user saved in keychain.
+/// @return `YES` if there is a previous user sign-in saved in keychain.
 - (BOOL)hasPreviousSignIn;
 
-/// Attempts to restore a previously authenticated user without interaction.
+/// Attempts to restore a previous user sign-in without interaction.
 ///
 /// @param completion The block that is called on completion.  This block will be called asynchronously
 ///     on the main queue.
 - (void)restorePreviousSignInWithCompletion:(nullable void (^)(GIDGoogleUser *_Nullable user,
                                                                NSError *_Nullable error))completion;
 
-/// Marks current user as being in the signed out state.
+/// Signs out the `currentUser`, removing it from the keychain.
 - (void)signOut;
 
-/// Disconnects the current user from the app and revokes previous authentication. If the operation
-/// succeeds, the OAuth 2.0 token is also removed from keychain.
+/// Disconnects the `currentUser` by signing them out and revoking all OAuth2 scope grants made to the app.
 ///
 /// @param completion The optional block that is called on completion.
 ///     This block will be called asynchronously on the main queue.
 - (void)disconnectWithCompletion:(nullable void (^)(NSError *_Nullable error))completion;
 
 #if TARGET_OS_IOS || TARGET_OS_MACCATALYST
+
 /// Starts an interactive sign-in flow on iOS.
 ///
 /// The completion will be called at the end of this process.  Any saved sign-in state will be
@@ -114,7 +114,7 @@ typedef NS_ERROR_ENUM(kGIDSignInErrorDomain, GIDSignInErrorCode) {
 /// @param presentingViewController The view controller used to present `SFSafariViewContoller` on
 ///     iOS 9 and 10 and to supply `presentationContextProvider` for `ASWebAuthenticationSession` on
 ///     iOS 13+.
-/// @param completion The `GIDSignInCompletion` block that is called on completion.  This block will
+/// @param completion The optional block that is called on completion.  This block will
 ///     be called asynchronously on the main queue.
 - (void)signInWithPresentingViewController:(UIViewController *)presentingViewController
                                 completion:(nullable void (^)(GIDUserAuth *_Nullable userAuth,
@@ -133,7 +133,7 @@ typedef NS_ERROR_ENUM(kGIDSignInErrorDomain, GIDSignInErrorCode) {
 ///     iOS 13+.
 /// @param hint An optional hint for the authorization server, for example the user's ID or email
 ///     address, to be prefilled if possible.
-/// @param completion The `GIDSignInCompletion` block that is called on completion.  This block will
+/// @param completion The optional block that is called on completion.  This block will
 ///     be called asynchronously on the main queue.
 - (void)signInWithPresentingViewController:(UIViewController *)presentingViewController
                                       hint:(nullable NSString *)hint
@@ -153,7 +153,7 @@ typedef NS_ERROR_ENUM(kGIDSignInErrorDomain, GIDSignInErrorCode) {
 /// @param hint An optional hint for the authorization server, for example the user's ID or email
 ///     address, to be prefilled if possible.
 /// @param additionalScopes An optional array of scopes to request in addition to the basic profile scopes.
-/// @param completion The `GIDSignInCompletion` block that is called on completion.  This block will
+/// @param completion The optional block that is called on completion.  This block will
 ///     be called asynchronously on the main queue.
 
 - (void)signInWithPresentingViewController:(UIViewController *)presentingViewController
@@ -164,6 +164,7 @@ typedef NS_ERROR_ENUM(kGIDSignInErrorDomain, GIDSignInErrorCode) {
     NS_EXTENSION_UNAVAILABLE("The sign-in flow is not supported in App Extensions.");
 
 #elif TARGET_OS_OSX
+
 /// Starts an interactive sign-in flow on macOS.
 ///
 /// The completion will be called at the end of this process.  Any saved sign-in state will be
@@ -172,7 +173,7 @@ typedef NS_ERROR_ENUM(kGIDSignInErrorDomain, GIDSignInErrorCode) {
 /// `restorePreviousSignInWithCompletion:` method to restore a previous sign-in.
 ///
 /// @param presentingWindow The window used to supply `presentationContextProvider` for `ASWebAuthenticationSession`.
-/// @param completion The `GIDSignInCompletion` block that is called on completion.  This block will
+/// @param completion The optional block that is called on completion.  This block will
 ///     be called asynchronously on the main queue.
 - (void)signInWithPresentingWindow:(NSWindow *)presentingWindow
                         completion:(nullable void (^)(GIDUserAuth *_Nullable userAuth,
@@ -188,7 +189,7 @@ typedef NS_ERROR_ENUM(kGIDSignInErrorDomain, GIDSignInErrorCode) {
 /// @param presentingWindow The window used to supply `presentationContextProvider` for `ASWebAuthenticationSession`.
 /// @param hint An optional hint for the authorization server, for example the user's ID or email
 ///     address, to be prefilled if possible.
-/// @param completion The `GIDSignInCompletion` block that is called on completion.  This block will
+/// @param completion The optional block that is called on completion.  This block will
 ///     be called asynchronously on the main queue.
 - (void)signInWithPresentingWindow:(NSWindow *)presentingWindow
                               hint:(nullable NSString *)hint
@@ -206,7 +207,7 @@ typedef NS_ERROR_ENUM(kGIDSignInErrorDomain, GIDSignInErrorCode) {
 /// @param hint An optional hint for the authorization server, for example the user's ID or email
 ///     address, to be prefilled if possible.
 /// @param additionalScopes An optional array of scopes to request in addition to the basic profile scopes.
-/// @param completion The `GIDSignInCompletion` block that is called on completion.  This block will
+/// @param completion The optional block that is called on completion.  This block will
 ///     be called asynchronously on the main queue.
 - (void)signInWithPresentingWindow:(NSWindow *)presentingWindow
                               hint:(nullable NSString *)hint

GoogleSignIn/Sources/Public/GoogleSignIn/GIDSignInButton.h

@@ -42,10 +42,10 @@ typedef NS_ENUM(NSInteger, GIDSignInButtonColorScheme) {
 
 /// This class provides the "Sign in with Google" button.
 ///
-/// You can instantiate this class programmatically or from a NIB file. You
-/// should connect this control to an `IBAction`, or something similar, that
-/// calls signInWithConfiguration:presentingViewController:callback: on
-/// `GIDSignIn` and add it to your view hierarchy.
+/// You can instantiate this class programmatically or from a NIB file. You should connect this
+/// control to an `IBAction`, or something similar, that calls
+/// signInWithPresentingViewController:completion: on `GIDSignIn` and add it to your view
+/// hierarchy.
 @interface GIDSignInButton : UIControl
 
 /// The layout style for the sign-in button.

GoogleSignIn/Sources/Public/GoogleSignIn/GIDToken.h

@@ -18,7 +18,7 @@
 
 NS_ASSUME_NONNULL_BEGIN
 
-/// This class represents the basic information of a token.
+/// This class represents an OAuth2 or OpenID Connect token.
 @interface GIDToken : NSObject <NSSecureCoding>
 
 /// The token string.