[flutter_appauth_platform_interface] cleanup API docs and format code (MaikuB#117)

* update API docs

* migrate example app 's XCode project

* update changelog

* format constructors

* Revert "migrate example app 's XCode project"

This reverts commit 508eb65.

* fix grammar in changelog

* add more API docs around properties related to additional parameters

* update wording for platform-specific properties

Author: MaikuB

flutter_appauth_platform_interface/CHANGELOG.md

@@ -1,3 +1,7 @@
+## [1.0.3]
+
+* Added `preferEphemeralSession` to `AuthorizationRequest` and `AuthorizationTokenRequest` classes. Thanks to the PR from [Matthew Smith](https://github.com/matthewtsmith).
+
 ## [1.0.2]
 
 * Fixes [issue #86](https://github.com/MaikuB/flutter_appauth/issues/86) where there was an error on casting `tokenAdditionalParameters` property upon calling the `token()` method. Thanks to the PR from [Sven](https://github.com/svendroid)

flutter_appauth_platform_interface/lib/src/authorization_parameters.dart

@@ -1,15 +1,15 @@
 import 'mappable.dart';
 
 mixin AuthorizationParameters on Mappable {
-  /// Hint to the Authorization Server about the login identifier the End-User might use to log in
+  /// Hint to the Authorization Server about the login identifier the End-User might use to log in.
   String loginHint;
 
-  /// list of ASCII string values that specifies whether the Authorization Server prompts the End-User for reauthentication and consent
+  /// List of ASCII string values that specifies whether the Authorization Server prompts the End-User for reauthentication and consent.
   List<String> promptValues;
 
-  /// Whether to use an ephemeral session and not share the cookies across the OS
+  /// Whether to use an ephemeral session that prevents cookies and other browser data being shared with the user's normal browser session.
   ///
-  /// iOS only
+  /// This property is only applicable to iOS versions 13 and above.
   bool preferEphemeralSession;
 
   @override

flutter_appauth_platform_interface/lib/src/authorization_request.dart

@@ -2,19 +2,22 @@ import 'authorization_parameters.dart';
 import 'authorization_service_configuration.dart';
 import 'common_request_details.dart';
 
-/// The details of an authorization request to get an authorization code
+/// The details of an authorization request to get an authorization code.
 class AuthorizationRequest extends CommonRequestDetails
     with AuthorizationParameters {
-  AuthorizationRequest(String clientId, String redirectUrl,
-      {String loginHint,
-      List<String> scopes,
-      AuthorizationServiceConfiguration serviceConfiguration,
-      Map<String, String> additionalParameters,
-      String issuer,
-      String discoveryUrl,
-      List<String> promptValues,
-      bool allowInsecureConnections = false,
-      bool preferEphemeralSession = false}) {
+  AuthorizationRequest(
+    String clientId,
+    String redirectUrl, {
+    String loginHint,
+    List<String> scopes,
+    AuthorizationServiceConfiguration serviceConfiguration,
+    Map<String, String> additionalParameters,
+    String issuer,
+    String discoveryUrl,
+    List<String> promptValues,
+    bool allowInsecureConnections = false,
+    bool preferEphemeralSession = false,
+  }) {
     this.clientId = clientId;
     this.redirectUrl = redirectUrl;
     this.scopes = scopes;

flutter_appauth_platform_interface/lib/src/authorization_response.dart

@@ -1,13 +1,16 @@
 class AuthorizationResponse {
-  AuthorizationResponse(this.authorizationCode, this.codeVerifier,
-      this.authorizationAdditionalParameters);
+  AuthorizationResponse(
+    this.authorizationCode,
+    this.codeVerifier,
+    this.authorizationAdditionalParameters,
+  );
 
-  /// The authorization code
+  /// The authorization code.
   final String authorizationCode;
 
-  /// The code verifier generated by AppAuth when issue the authorization request. Use this when exchanging the [authorizationCode] for a token
+  /// The code verifier generated by AppAuth when issue the authorization request. Use this when exchanging the [authorizationCode] for a token.
   final String codeVerifier;
 
-  /// Additional parameters included in the response
+  /// Additional parameters included in the response.
   final Map<String, dynamic> authorizationAdditionalParameters;
 }

flutter_appauth_platform_interface/lib/src/authorization_service_configuration.dart

@@ -1,7 +1,8 @@
 class AuthorizationServiceConfiguration {
   AuthorizationServiceConfiguration(
-      this.authorizationEndpoint, this.tokenEndpoint)
-      : assert(tokenEndpoint != null && authorizationEndpoint != null,
+    this.authorizationEndpoint,
+    this.tokenEndpoint,
+  ) : assert(tokenEndpoint != null && authorizationEndpoint != null,
             'Must specify both the authorization and token endpoints');
 
   final String authorizationEndpoint;

flutter_appauth_platform_interface/lib/src/authorization_token_request.dart

@@ -6,18 +6,20 @@ import 'token_request.dart';
 /// Details required for a combined authorization and code exchange request
 class AuthorizationTokenRequest extends TokenRequest
     with AuthorizationParameters {
-  AuthorizationTokenRequest(String clientId, String redirectUrl,
-      {String loginHint,
-      String clientSecret,
-      List<String> scopes,
-      AuthorizationServiceConfiguration serviceConfiguration,
-      Map<String, String> additionalParameters,
-      String issuer,
-      String discoveryUrl,
-      List<String> promptValues,
-      bool allowInsecureConnections = false,
-      bool preferEphemeralSession = false})
-      : super(
+  AuthorizationTokenRequest(
+    String clientId,
+    String redirectUrl, {
+    String loginHint,
+    String clientSecret,
+    List<String> scopes,
+    AuthorizationServiceConfiguration serviceConfiguration,
+    Map<String, String> additionalParameters,
+    String issuer,
+    String discoveryUrl,
+    List<String> promptValues,
+    bool allowInsecureConnections = false,
+    bool preferEphemeralSession = false,
+  }) : super(
           clientId,
           redirectUrl,
           clientSecret: clientSecret,

flutter_appauth_platform_interface/lib/src/authorization_token_response.dart

@@ -1,17 +1,18 @@
 import 'token_response.dart';
 
-/// The details from making a successful combined authorization and token exchange request
+/// The details from making a successful combined authorization and token exchange request.
 class AuthorizationTokenResponse extends TokenResponse {
   AuthorizationTokenResponse(
-      String accessToken,
-      String refreshToken,
-      DateTime accessTokenExpirationDateTime,
-      String idToken,
-      String tokenType,
-      this.authorizationAdditionalParameters,
-      Map<String, dynamic> tokenAdditionalParameters)
-      : super(accessToken, refreshToken, accessTokenExpirationDateTime, idToken,
+    String accessToken,
+    String refreshToken,
+    DateTime accessTokenExpirationDateTime,
+    String idToken,
+    String tokenType,
+    this.authorizationAdditionalParameters,
+    Map<String, dynamic> tokenAdditionalParameters,
+  ) : super(accessToken, refreshToken, accessTokenExpirationDateTime, idToken,
             tokenType, tokenAdditionalParameters);
 
+  /// Contains additional parameters returned by the authorization server from making the authorization request.
   final Map<String, dynamic> authorizationAdditionalParameters;
 }

flutter_appauth_platform_interface/lib/src/common_request_details.dart

@@ -2,28 +2,30 @@ import 'authorization_service_configuration.dart';
 import 'mappable.dart';
 
 class CommonRequestDetails implements Mappable {
-  /// The client id
+  /// The client id.
   String clientId;
 
-  /// The issuer
+  /// The issuer.
   String issuer;
 
-  /// The URL of where the discovery document can be found
+  /// The URL of where the discovery document can be found.
   String discoveryUrl;
 
-  /// The redirect URL
+  /// The redirect URL.
   String redirectUrl;
 
-  /// The request scopes
+  /// The request scopes.
   List<String> scopes;
 
-  /// The details of the OAuth 2.0 endpoints that can be explicitly when discovery isn't used or not possible
+  /// The details of the OAuth 2.0 endpoints that can be explicitly when discovery isn't used or not possible.
   AuthorizationServiceConfiguration serviceConfiguration;
 
-  /// Additional parameters to include in the request
+  /// Additional parameters to include in the request.
   Map<String, String> additionalParameters;
 
-  /// Whether to allow non-HTTPS endpoints (only applicable on Android)
+  /// Whether to allow non-HTTPS endpoints.
+  ///
+  /// This property is only applicable to Android.
   bool allowInsecureConnections;
 
   @override

flutter_appauth_platform_interface/lib/src/flutter_appauth_platform.dart

@@ -28,19 +28,19 @@ abstract class FlutterAppAuthPlatform extends PlatformInterface {
     _instance = instance;
   }
 
-  /// Convenience method for authorizing and then exchanges the authorization grant code
+  /// Convenience method for authorizing and then exchanges the authorization grant code.
   Future<AuthorizationTokenResponse> authorizeAndExchangeCode(
       AuthorizationTokenRequest request) {
     throw UnimplementedError(
         'authorizeAndExchangeCode() has not been implemented');
   }
 
-  /// Sends an authorization request
+  /// Sends an authorization request.
   Future<AuthorizationResponse> authorize(AuthorizationRequest request) {
     throw UnimplementedError('authorize() has not been implemented');
   }
 
-  /// For exchanging tokens
+  /// For exchanging tokens.
   Future<TokenResponse> token(TokenRequest request) {
     throw UnimplementedError('token() has not been implemented');
   }

flutter_appauth_platform_interface/lib/src/token_request.dart

@@ -2,7 +2,7 @@ import 'authorization_service_configuration.dart';
 import 'common_request_details.dart';
 import 'grant_types.dart';
 
-/// Details for a token exchange request
+/// Details for a token exchange request.
 class TokenRequest with CommonRequestDetails {
   TokenRequest(
     String clientId,
@@ -34,16 +34,18 @@ class TokenRequest with CommonRequestDetails {
     this.allowInsecureConnections = allowInsecureConnections;
   }
 
-  /// The client secret
+  /// The client secret.
   final String clientSecret;
 
-  /// The refresh token
+  /// The refresh token.
   final String refreshToken;
 
-  /// The grant type. This would be inferred if it hasn't been set based on if a refresh token or authorization code has been specified
+  /// The grant type.
+  ///
+  /// If this is not specified then it will be inferred based on if [refreshToken] or [authorizationCode] has been specified.
   final String grantType;
 
-  /// The authorization code
+  /// The authorization code.
   final String authorizationCode;
 
   /// The code verifier to be sent with the authorization code. This should match the code verifier used when performing the authorization request

flutter_appauth_platform_interface/lib/src/token_response.dart

@@ -1,22 +1,33 @@
 /// Details from making a successful token exchange
 class TokenResponse {
   TokenResponse(
-      this.accessToken,
-      this.refreshToken,
-      this.accessTokenExpirationDateTime,
-      this.idToken,
-      this.tokenType,
-      this.tokenAdditionalParameters);
+    this.accessToken,
+    this.refreshToken,
+    this.accessTokenExpirationDateTime,
+    this.idToken,
+    this.tokenType,
+    this.tokenAdditionalParameters,
+  );
 
+  /// The access token returned by the authorization server.
   final String accessToken;
 
+  /// The refresh token returned by the authorization server.
   final String refreshToken;
 
+  /// Indicates when [accessToken] will expire.
+  ///
+  /// To ensure applications have continue to use valid access tokens, they
+  /// will generally use the refresh token to get a new access token
+  /// before it expires.
   final DateTime accessTokenExpirationDateTime;
 
+  /// The id token returned by the authorization server.
   final String idToken;
 
+  /// The type of token returned by the authorization server.
   final String tokenType;
 
+  /// Contains additional parameters returned by the authorization server from making the token request.
   final Map<String, dynamic> tokenAdditionalParameters;
 }