updated documentation (#521)

flutter_appauth/CHANGELOG.md

@@ -2,6 +2,8 @@
 
 * **Breaking change** all methods have now been made to return non-nullable types
 * [iOS][macOS] bumped AppAuth iOS dependency to 1.7.5
+* Updated API docs with more details
+* Updated readme with more details on essential knowledge and links to OAuth 2.0 specifications
 
 # 7.0.0-dev.2
 

flutter_appauth/README.md

@@ -18,8 +18,7 @@ A Flutter bridge for AppAuth (https://appauth.io) used authenticating and author
 
 ## Getting Started
 
-Please see the example that demonstrates how to sign into the demo IdentityServer instance (https://demo.duendesoftware.com). It has also been tested with Azure B2C and Google Sign-in. It is suggested that developers check the documentation of the identity provider they are using to see what capabilities it supports e.g. how to logout, what values of the `prompt` parameter it supports etc. API docs can be found [here](https://pub.dartlang.org/documentation/flutter_appauth/latest/)
-
+Please see the example that demonstrates how to sign into the demo IdentityServer instance (https://demo.duendesoftware.com). It has also been tested with Azure B2C, Auth0, FusionAuth and Google Sign-in. Developers should check the documentation of the identity provider they are using to see what capabilities it supports (e.g. how to logout, what values of the `prompt` parameter it supports etc) and how to configure/register their application with the identity provider. Understanding [OAuth 2.0](https://datatracker.ietf.org/doc/html/rfc6749) is also essential, especially when it comes to [best practices for native mobile apps](https://datatracker.ietf.org/doc/html/rfc8252).
 
 The first step is to create an instance of the plugin
 
@@ -220,6 +219,11 @@ Go to the `Info.plist` for your iOS/macOS app to specify the custom scheme so th
 
 Note: iOS apps generate a file called `cache.db` which contains the table `cfurl_cache_receiver_data`. This table will contain the access token obtained after the login is completed. If the potential data leak represents a threat for your application then you can disable the information caching for the entire iOS app (ex. https://kunalgupta1508.medium.com/data-leakage-with-cache-db-2d311582cf23).
 
+
+## API docs
+
+API docs can be found [here](https://pub.dartlang.org/documentation/flutter_appauth/latest/)
+
 ## FAQs
 
 **When connecting to Azure B2C or Azure AD, the login request redirects properly on Android but not on iOS. What's going on?**

flutter_appauth/lib/src/flutter_appauth.dart

@@ -9,16 +9,26 @@ class FlutterAppAuth {
  return FlutterAppAuthPlatform.instance.authorizeAndExchangeCode(request);
  }
 
- /// Sends an authorization request
+ /// Sends an authorization request.
+ ///
+ /// This is done by sending a request to the authorization server's
+ /// [authorization endpoint](https://datatracker.ietf.org/doc/html/rfc6749#section-3.1).
  Future<AuthorizationResponse> authorize(AuthorizationRequest request) {
  return FlutterAppAuthPlatform.instance.authorize(request);
  }
 
- /// For exchanging tokens
+ /// For exchanging tokens.
+ ///
+ /// This is done by sending a request to the authorization server's
+ /// [token endpoint](https://datatracker.ietf.org/doc/html/rfc6749#section-3.2).
  Future<TokenResponse> token(TokenRequest request) {
  return FlutterAppAuthPlatform.instance.token(request);
  }
 
+ /// Performs an end session/logout request.
+ ///
+ /// This is done by sending a request to the authorization server's
+ /// end session endpoint per the [RP-initiated logout spec](https://openid.net/specs/openid-connect-rpinitiated-1_0.html).
  Future<EndSessionResponse> endSession(EndSessionRequest request) {
  return FlutterAppAuthPlatform.instance.endSession(request);
  }

flutter_appauth_platform_interface/CHANGELOG.md

@@ -1,6 +1,7 @@
 ## [7.0.0-dev.3]
 
 * **Breaking change** all methods have now been made to return non-nullable types
+* Updated API docs with more details
 
 ## [7.0.0-dev.2]
 

flutter_appauth_platform_interface/lib/src/end_session_request.dart

@@ -1,6 +1,7 @@
 import 'package:flutter_appauth_platform_interface/flutter_appauth_platform_interface.dart';
 import 'package:flutter_appauth_platform_interface/src/accepted_authorization_service_configuration_details.dart';
 
+/// Represents an end session request.
 class EndSessionRequest with AcceptedAuthorizationServiceConfigurationDetails {
  EndSessionRequest({
  this.idTokenHint,

flutter_appauth_platform_interface/lib/src/end_session_response.dart

@@ -1,3 +1,4 @@
+/// Represents the response from performing an end session/logout request.
 class EndSessionResponse {
  EndSessionResponse(this.state);
 

flutter_appauth_platform_interface/lib/src/flutter_appauth_platform.dart

@@ -40,15 +40,25 @@ abstract class FlutterAppAuthPlatform extends PlatformInterface {
  }
 
  /// Sends an authorization request.
+ ///
+ /// This is done by sending a request to the authorization server's
+ /// [authorization endpoint](https://datatracker.ietf.org/doc/html/rfc6749#section-3.1).
  Future<AuthorizationResponse> authorize(AuthorizationRequest request) {
  throw UnimplementedError('authorize() has not been implemented');
  }
 
  /// For exchanging tokens.
+ ///
+ /// This is done by sending a request to the authorization server's
+ /// [token endpoint](https://datatracker.ietf.org/doc/html/rfc6749#section-3.2).
  Future<TokenResponse> token(TokenRequest request) {
  throw UnimplementedError('token() has not been implemented');
  }
 
+ /// Performs an end session/logout request.
+ ///
+ /// This is done by sending a request to the authorization server's
+ /// end session endpoint per the [RP-initiated logout spec](https://openid.net/specs/openid-connect-rpinitiated-1_0.html).
  Future<EndSessionResponse> endSession(EndSessionRequest request) {
  throw UnimplementedError('endSession() has not been implemented');
  }