[google_sign_in_platform_interface] Add missing docs (flutter-team-archive#2359)

Author: Michael Klimushyn

packages/google_sign_in/google_sign_in_platform_interface/CHANGELOG.md

@@ -1,3 +1,7 @@
+## 1.0.2
+
+* Add missing documentation.
+
 ## 1.0.1
 
 * Switch away from quiver_hashcode.

packages/google_sign_in/google_sign_in_platform_interface/analysis_options.yaml

@@ -61,8 +61,23 @@ abstract class GoogleSignInPlatform {
   /// if the provided instance is a class implemented with `implements`.
   void _verifyProvidesDefaultImplementations() {}
 
-  /// Initializes the plugin. You must call this method before calling other methods.
-  /// See: https://developers.google.com/identity/sign-in/web/reference#gapiauth2initparams
+  /// Initializes the plugin. You must call this method before calling other
+  /// methods.
+  ///
+  /// The [hostedDomain] argument specifies a hosted domain restriction. By
+  /// setting this, sign in will be restricted to accounts of the user in the
+  /// specified domain. By default, the list of accounts will not be restricted.
+  ///
+  /// The list of [scopes] are OAuth scope codes to request when signing in.
+  /// These scope codes will determine the level of data access that is granted
+  /// to your application by the user. The full list of available scopes can be
+  /// found here: <https://developers.google.com/identity/protocols/googlescopes>
+  ///
+  /// The [signInOption] determines the user experience. [SigninOption.games] is
+  /// only supported on Android.
+  ///
+  /// See:
+  /// https://developers.google.com/identity/sign-in/web/reference#gapiauth2initparams
   Future<void> init(
       {@required String hostedDomain,
       List<String> scopes,

packages/google_sign_in/google_sign_in_platform_interface/lib/google_sign_in_platform_interface.dart

@@ -13,6 +13,8 @@ import 'utils.dart';
 
 /// An implementation of [GoogleSignInPlatform] that uses method channels.
 class MethodChannelGoogleSignIn extends GoogleSignInPlatform {
+  /// This is only exposed for test purposes. It shouldn't be used by clients of
+  /// the plugin as it may break or change at any time.
   @visibleForTesting
   MethodChannel channel =
       const MethodChannel('plugins.flutter.io/google_sign_in');

packages/google_sign_in/google_sign_in_platform_interface/lib/src/method_channel_google_sign_in.dart

@@ -4,15 +4,62 @@
 
 import 'package:quiver/core.dart';
 
-enum SignInOption { standard, games }
+/// Default configuration options to use when signing in.
+///
+/// See also https://developers.google.com/android/reference/com/google/android/gms/auth/api/signin/GoogleSignInOptions
+enum SignInOption {
+  /// Default configuration. Provides stable user ID and basic profile information.
+  ///
+  /// See also https://developers.google.com/android/reference/com/google/android/gms/auth/api/signin/GoogleSignInOptions.html#DEFAULT_SIGN_IN.
+  standard,
 
+  /// Recommended configuration for Games sign in.
+  ///
+  /// This is currently only supported on Android and will throw an error if used
+  /// on other platforms.
+  ///
+  /// See also https://developers.google.com/android/reference/com/google/android/gms/auth/api/signin/GoogleSignInOptions.html#public-static-final-googlesigninoptions-default_games_sign_in.
+  games
+}
+
+/// Holds information about the signed in user.
 class GoogleSignInUserData {
+  /// Uses the given data to construct an instance. Any of these parameters
+  /// could be null.
   GoogleSignInUserData(
       {this.displayName, this.email, this.id, this.photoUrl, this.idToken});
+
+  /// The display name of the signed in user.
+  ///
+  /// Not guaranteed to be present for all users, even when configured.
   String displayName;
+
+  /// The email address of the signed in user.
+  ///
+  /// Applications should not key users by email address since a Google account's
+  /// email address can change. Use [id] as a key instead.
+  ///
+  /// _Important_: Do not use this returned email address to communicate the
+  /// currently signed in user to your backend server. Instead, send an ID token
+  /// which can be securely validated on the server. See [idToken].
   String email;
+
+  /// The unique ID for the Google account.
+  ///
+  /// This is the preferred unique key to use for a user record.
+  ///
+  /// _Important_: Do not use this returned Google ID to communicate the
+  /// currently signed in user to your backend server. Instead, send an ID token
+  /// which can be securely validated on the server. See [idToken].
   String id;
+
+  /// The photo url of the signed in user if the user has a profile picture.
+  ///
+  /// Not guaranteed to be present for all users, even when configured.
   String photoUrl;
+
+  /// A token that can be sent to your own server to verify the authentication
+  /// data.
   String idToken;
 
   @override
@@ -32,9 +79,15 @@ class GoogleSignInUserData {
   }
 }
 
+/// Holds authentication data after sign in.
 class GoogleSignInTokenData {
+  /// Either or both parameters may be null.
   GoogleSignInTokenData({this.idToken, this.accessToken});
+
+  /// An OpenID Connect ID token for the authenticated user.
   String idToken;
+
+  /// The OAuth2 access token used to access Google services.
   String accessToken;
 
   @override

packages/google_sign_in/google_sign_in_platform_interface/lib/src/types.dart

@@ -4,7 +4,7 @@ author: Flutter Team <flutter-dev@googlegroups.com>
 homepage: https://github.com/flutter/plugins/tree/master/packages/google_sign_in/google_sign_in_platform_interface
 # NOTE: We strongly prefer non-breaking changes, even at the expense of a
 # less-clean API. See https://flutter.dev/go/platform-interface-breaking-changes
-version: 1.0.1
+version: 1.0.2
 
 dependencies:
   flutter:

packages/google_sign_in/google_sign_in_platform_interface/pubspec.yaml

@@ -17,7 +17,6 @@ CUSTOM_ANALYSIS_PLUGINS=(
   "in_app_purchase"
   "camera"
   "google_sign_in/google_sign_in"
-  "google_sign_in/google_sign_in_platform_interface"
   "google_sign_in/google_sign_in_web"
 )
 # Comma-separated string of the list above