passkeys: add dartdoc comments on format requirements

packages/passkeys/passkeys_platform_interface/lib/types/authenticate_request.dart

@@ -1,23 +1,53 @@
 import 'package:passkeys_platform_interface/types/credential.dart';
 import 'package:passkeys_platform_interface/types/mediation.dart';
 
+/// The [AuthenticateRequestType] is used to create an authentication request and send it to the
+/// platform.
 class AuthenticateRequestType {
   /// Constructs a new instance.
   const AuthenticateRequestType({
     required this.relyingPartyId,
     required this.challenge,
+    required this.mediation,
+    required this.preferImmediatelyAvailableCredentials,
     this.timeout,
     this.userVerification,
     this.allowCredentials,
-    required this.mediation,
-    required this.preferImmediatelyAvailableCredentials,
   });
 
+  /// The relying party ID.
+  /// This is typically the domain of the website that is requesting authentication.
   final String relyingPartyId;
+
+  /// The Base64URL encoded challenge _without_ padding.
   final String challenge;
+
+  /// The timeout in milliseconds.
+  /// This is the maximum time the user has to respond to the authentication request.
   final int? timeout;
+
+  /// The user verification requirement.
+  /// This can be one of the following values:
+  /// - `required`: The user must be verified.
+  /// - `preferred`: The user may be verified, but it's not required.
+  /// - `discouraged`: The user should not be verified, but it's not required.
+  /// If this value is `null`, the default value is `preferred`.
   final String? userVerification;
+
+  /// The list of allowed credentials that the user can use to authenticate.
+  /// If this value is `null`, the user can use any credential.
   final List<CredentialType>? allowCredentials;
+
+  /// The mediation type.
+  /// This can be one of the following values:
+  /// - `silent`: The authentication request is silent and does not require user interaction.
+  /// - `optional`: The authentication request is optional and may require user interaction.
+  /// - `conditional`: The authentication request is conditional and may require user interaction.
+  /// - `required`: The authentication request is required and must require user interaction.
   final MediationType mediation;
+
+  /// The prefer immediately available credentials flag.
+  /// If this value is `true`, the platform will prefer credentials that are
+  /// immediately available, such as those that are stored on the device.
   final bool preferImmediatelyAvailableCredentials;
 }

packages/passkeys/passkeys_platform_interface/lib/types/credential.dart

@@ -2,7 +2,8 @@ import 'package:json_annotation/json_annotation.dart';
 
 part 'credential.g.dart';
 
-/// The [CredentialType] class wraps the data of a credential it can be used to explicitly exclude or allow credentials.
+/// The [CredentialType] class wraps the data of a credential it can be used to
+/// explicitly exclude or allow credentials.
 @JsonSerializable()
 class CredentialType {
   /// Constructs a new instance.
@@ -19,7 +20,7 @@ class CredentialType {
   /// The type of the credential.
   final String type;
 
-  /// The ID of the credential.
+  /// The Base64URL encoded credential ID _without_ padding.
   final String id;
 
   /// The transports of the credential.

packages/passkeys/passkeys_platform_interface/lib/types/mediation.dart

@@ -1,6 +1,20 @@
+/// Defines how user mediation (interaction) should be handled during credential operations.
 enum MediationType {
+  /// Credentials are presented in a non-modal dialog. User can dismiss by clicking outside.
+  /// Used for scenarios where immediate user interaction is preferred but not required.
+  /// Only available if the credential interfaces support conditional mediation.
   Conditional,
+
+  /// Allows automatic credential handover if possible, but will prompt for user
+  /// mediation if required. This is the default behavior for credential retrieval.
   Optional,
+
+  /// Always requires user mediation for credential operations, even if silent
+  /// access would be possible. Useful for reauthentication or user-switching scenarios.
   Required,
+
+  /// Suppresses user mediation. Operations will return null if user interaction
+  /// would be needed. Useful for "Keep me signed in" features where automatic
+  /// sign-in should be attempted without bothering the user.
   Silent,
 }

packages/passkeys/passkeys_platform_interface/lib/types/pubkeycred_param.dart

@@ -2,6 +2,10 @@ import 'package:json_annotation/json_annotation.dart';
 
 part 'pubkeycred_param.g.dart';
 
+/// The [PubKeyCredParamType] class wraps the data of a public key credential
+/// parameter.
+/// It is used to specify the type and algorithm of the public key credential
+/// that is being requested.
 @JsonSerializable()
 class PubKeyCredParamType {
   /// Constructs a new instance.
@@ -14,10 +18,12 @@ class PubKeyCredParamType {
   factory PubKeyCredParamType.fromJson(Map<String, dynamic> json) =>
       _$PubKeyCredParamTypeFromJson(json);
 
-  ///
+  /// The type of the public key credential.
   final String type;
 
-  ///
+  /// The algorithm used for the public key credential, i.e. `-7` for `ES256` or
+  /// `-257` for RS256.
+  /// See [IANA COSE](https://www.iana.org/assignments/cose/cose.xhtml#algorithms) for a list of all options.
   final int alg;
 
   /// Converts this instance to a JSON map.

packages/passkeys/passkeys_platform_interface/lib/types/register_request.dart

@@ -4,7 +4,10 @@ import 'package:passkeys_platform_interface/types/pubkeycred_param.dart';
 import 'package:passkeys_platform_interface/types/relying_party.dart';
 import 'package:passkeys_platform_interface/types/user.dart';
 
+/// The [RegisterRequestType] is used to create a registration request and send it to the
+/// platform.
 class RegisterRequestType {
+  /// Constructs a new instance.
   const RegisterRequestType({
     required this.challenge,
     required this.relyingParty,
@@ -16,12 +19,33 @@ class RegisterRequestType {
     this.attestation,
   });
 
+  /// The Base64URL encoded challenge _without_ padding.
   final String challenge;
+
+  /// The relying party.
   final RelyingPartyType relyingParty;
+
+  /// The user.
   final UserType user;
+
+  /// The authenticator selection type.
   final AuthenticatorSelectionType authSelectionType;
+
+  /// A list of public key credential parameters.
   final List<PubKeyCredParamType>? pubKeyCredParams;
+
+  /// A list of credentials to exclude from the registration.
+  /// This is typically used to prevent the user from registering the same
+  /// credential multiple times.
   final List<CredentialType> excludeCredentials;
+
+  /// The timeout in milliseconds.
   final int? timeout;
+
+  /// The requested attestation level. Controls how the authenticator's attestation
+  /// information is conveyed to the relying party. Possible values are:
+  /// - "none": Replaces identifying information with non-identifying versions
+  /// - "indirect": May replace attestation data with privacy-friendly versions
+  /// - "direct"/"enterprise": Conveys unaltered attestation information
   final String? attestation;
 }

packages/passkeys/passkeys_platform_interface/lib/types/relying_party.dart

@@ -2,6 +2,8 @@ import 'package:json_annotation/json_annotation.dart';
 
 part 'relying_party.g.dart';
 
+/// The [RelyingPartyType] class wraps the data of a relying party.
+/// It is used to identify the party that is requesting authentication.
 @JsonSerializable()
 class RelyingPartyType {
   /// Constructs a new instance.
@@ -10,14 +12,17 @@ class RelyingPartyType {
     required this.id,
   });
 
+  /// Constructs a new instance from a JSON map.
   factory RelyingPartyType.fromJson(Map<String, dynamic> json) =>
       _$RelyingPartyTypeFromJson(json);
 
-  ///
+  /// The display name of the relying party.
   final String name;
 
-  ///
+  /// The identifier of the relying party.
+  /// This is typically the domain of the website that is requesting authentication.
   final String id;
 
+  /// Converts this instance to a JSON map.
   Map<String, dynamic> toJson() => _$RelyingPartyTypeToJson(this);
 }

packages/passkeys/passkeys_platform_interface/lib/types/user.dart

@@ -2,19 +2,27 @@ import 'package:json_annotation/json_annotation.dart';
 
 part 'user.g.dart';
 
+/// The [UserType] class wraps the data of a user..
 @JsonSerializable()
 class UserType {
-  factory UserType.fromJson(Map<String, dynamic> json) =>
-      _$UserTypeFromJson(json);
-
-  UserType({
+  /// Constructs a new instance.
+  const UserType({
     required this.displayName,
     required this.name,
     required this.id,
   });
 
+  /// Constructs a new instance from a JSON map.
+  factory UserType.fromJson(Map<String, dynamic> json) =>
+      _$UserTypeFromJson(json);
+
+  /// The display name of the user.
   final String displayName;
+
+  /// The name of the user.
   final String name;
+
+  /// The Base64URL encoded identifier _with_ padding.
   final String id;
 
   Map<String, dynamic> toJson() => _$UserTypeToJson(this);