add comments

packages/stream_chat/lib/src/client/client.dart

@@ -6,33 +6,31 @@ import 'package:dio/dio.dart';
 import 'package:logging/logging.dart';
 import 'package:rxdart/rxdart.dart';
 import 'package:stream_chat/src/client/channel.dart';
-import 'package:stream_chat/src/core/util/utils.dart';
+import 'package:stream_chat/src/client/retry_policy.dart';
-import 'package:stream_chat/src/core/error/error.dart';
-import 'package:stream_chat/src/location.dart';
-import 'package:stream_chat/src/ws/connection_status.dart';
 import 'package:stream_chat/src/core/api/attachment_file_uploader.dart';
 import 'package:stream_chat/src/core/api/requests.dart';
 import 'package:stream_chat/src/core/api/responses.dart';
-import 'package:stream_chat/src/client/retry_policy.dart';
-import 'package:stream_chat/src/ws/websocket.dart';
 import 'package:stream_chat/src/core/api/stream_chat_api.dart';
+import 'package:stream_chat/src/core/error/error.dart';
 import 'package:stream_chat/src/core/http/connection_id_manager.dart';
 import 'package:stream_chat/src/core/http/stream_http_client.dart';
 import 'package:stream_chat/src/core/http/token.dart';
 import 'package:stream_chat/src/core/http/token_manager.dart';
-import 'package:stream_chat/src/db/chat_persistence_client.dart';
-import 'package:stream_chat/src/event_type.dart';
 import 'package:stream_chat/src/core/models/attachment_file.dart';
 import 'package:stream_chat/src/core/models/channel_model.dart';
 import 'package:stream_chat/src/core/models/channel_state.dart';
 import 'package:stream_chat/src/core/models/event.dart';
+import 'package:stream_chat/src/core/models/filter.dart';
+import 'package:stream_chat/src/core/models/member.dart';
 import 'package:stream_chat/src/core/models/message.dart';
 import 'package:stream_chat/src/core/models/own_user.dart';
 import 'package:stream_chat/src/core/models/user.dart';
-
+import 'package:stream_chat/src/core/util/utils.dart';
-import 'package:stream_chat/src/core/models/filter.dart';
+import 'package:stream_chat/src/db/chat_persistence_client.dart';
-
+import 'package:stream_chat/src/event_type.dart';
-import 'package:stream_chat/src/core/models/member.dart';
+import 'package:stream_chat/src/location.dart';
+import 'package:stream_chat/src/ws/connection_status.dart';
+import 'package:stream_chat/src/ws/websocket.dart';
 
 /// Handler function used for logging records. Function requires a single
 /// [LogRecord] as the only parameter.
@@ -137,10 +135,10 @@ class StreamChatClient {
 
   late final RetryPolicy _retryPolicy;
 
-  // sync state of the channels present inside state, defaults to false
+  /// sync state of the channels present inside state, defaults to false
   bool _synced = false;
 
-  // the last dateTime at the which all the channels were synced
+  /// the last dateTime at the which all the channels were synced
   DateTime? _lastSyncedAt;
 
   /// The retry policy options getter

packages/stream_chat/lib/src/client/retry_policy.dart

@@ -2,6 +2,12 @@ import 'package:stream_chat/src/client/client.dart';
 import 'package:stream_chat/src/core/error/error.dart';
 
 /// The retry options
+/// When sending/updating/deleting a message any temporary error will trigger the retry policy
+/// The retry policy exposes 2 methods
+/// - shouldRetry: returns a boolean if the request should be retried
+/// - retryTimeout: How many milliseconds to wait till the next attempt
+///
+/// maxRetryAttempts is a hard limit on maximum retry attempts before giving up
 class RetryPolicy {
   /// Instantiate a new RetryPolicy
   RetryPolicy({

packages/stream_chat/lib/src/core/api/channel_api.dart

@@ -9,9 +9,9 @@ import 'package:stream_chat/src/core/models/event.dart';
 import 'package:stream_chat/src/core/models/filter.dart';
 import 'package:stream_chat/src/core/models/message.dart';
 
-///
+/// Defines the api dedicated to channel operations
 class ChannelApi {
-  ///
+  /// Initialize a new channel api
   ChannelApi(this._client);
 
   final StreamHttpClient _client;

packages/stream_chat/lib/src/core/api/device_api.dart

@@ -19,9 +19,9 @@ extension PushProviderX on PushProvider {
       }[this]!;
 }
 
-///
+/// Defines the api dedicated to device operations
 class DeviceApi {
-  ///
+  /// Initialize a new device api
   DeviceApi(this._client);
 
   final StreamHttpClient _client;

packages/stream_chat/lib/src/core/api/general_api.dart

@@ -6,9 +6,9 @@ import 'package:stream_chat/src/core/http/stream_http_client.dart';
 import 'package:stream_chat/src/core/models/filter.dart';
 import 'package:stream_chat/src/core/models/member.dart';
 
-///
+/// Defines the api dedicated to general operations
 class GeneralApi {
-  ///
+  /// Initialize a new general api
   GeneralApi(this._client);
 
   final StreamHttpClient _client;

packages/stream_chat/lib/src/core/api/guest_api.dart

@@ -2,14 +2,14 @@ import 'package:stream_chat/src/core/api/responses.dart';
 import 'package:stream_chat/src/core/http/stream_http_client.dart';
 import 'package:stream_chat/src/core/models/user.dart';
 
-///
+/// Defines the api dedicated to guest users operations
 class GuestApi {
-  ///
+  /// Initialize a new guest api
   GuestApi(this._client);
 
   final StreamHttpClient _client;
 
-  ///
+  /// Returns the information about guest user
   Future<ConnectGuestUserResponse> getGuestUser(User user) async {
     final response = await _client.post(
       '/guest',

packages/stream_chat/lib/src/core/api/message_api.dart

@@ -3,9 +3,9 @@ import 'package:stream_chat/src/core/api/responses.dart';
 import 'package:stream_chat/src/core/http/stream_http_client.dart';
 import 'package:stream_chat/src/core/models/message.dart';
 
-///
+/// Defines the api dedicated to messages operations
 class MessageApi {
-  ///
+  /// Initialize a new message api
   MessageApi(this._client);
 
   final StreamHttpClient _client;

packages/stream_chat/lib/src/core/api/moderation_api.dart

@@ -1,9 +1,9 @@
 import 'package:stream_chat/src/core/api/responses.dart';
 import 'package:stream_chat/src/core/http/stream_http_client.dart';
 
-///
+/// Defines the api dedicated to moderation operations
 class ModerationApi {
-  ///
+  /// Initialize a new moderation api
   ModerationApi(this._client);
 
   final StreamHttpClient _client;

packages/stream_chat/lib/src/core/api/responses.dart

@@ -1,5 +1,6 @@
 import 'package:json_annotation/json_annotation.dart';
 import 'package:stream_chat/src/client/client.dart';
+import 'package:stream_chat/src/core/error/error.dart';
 import 'package:stream_chat/src/core/models/channel_model.dart';
 import 'package:stream_chat/src/core/models/channel_state.dart';
 import 'package:stream_chat/src/core/models/device.dart';
@@ -9,7 +10,6 @@ import 'package:stream_chat/src/core/models/message.dart';
 import 'package:stream_chat/src/core/models/reaction.dart';
 import 'package:stream_chat/src/core/models/read.dart';
 import 'package:stream_chat/src/core/models/user.dart';
-import 'package:stream_chat/src/core/error/error.dart';
 
 part 'responses.g.dart';
 
@@ -20,17 +20,17 @@ class _BaseResponse {
 /// Model response for [StreamChatNetworkError] data
 @JsonSerializable()
 class ErrorResponse extends _BaseResponse {
-  ///
+  /// The http error code
   int? code;
 
-  ///
+  /// The message associated to the error code
   String? message;
 
-  ///
+  /// The backend error code
   @JsonKey(name: 'StatusCode')
   int? statusCode;
 
-  ///
+  /// A detailed message about the error
   String? moreInfo;
 
   /// Create a new instance from a json

packages/stream_chat/lib/src/core/api/stream_chat_api.dart

@@ -1,21 +1,21 @@
 import 'package:logging/logging.dart';
+import 'package:stream_chat/src/core/api/attachment_file_uploader.dart';
 import 'package:stream_chat/src/core/api/channel_api.dart';
 import 'package:stream_chat/src/core/api/device_api.dart';
 import 'package:stream_chat/src/core/api/general_api.dart';
 import 'package:stream_chat/src/core/api/guest_api.dart';
 import 'package:stream_chat/src/core/api/message_api.dart';
 import 'package:stream_chat/src/core/api/moderation_api.dart';
+import 'package:stream_chat/src/core/api/user_api.dart';
 import 'package:stream_chat/src/core/http/connection_id_manager.dart';
 import 'package:stream_chat/src/core/http/stream_http_client.dart';
-import 'package:stream_chat/src/core/api/user_api.dart';
 import 'package:stream_chat/src/core/http/token_manager.dart';
-import 'package:stream_chat/src/core/api/attachment_file_uploader.dart';
 
 export 'device_api.dart' show PushProvider;
 
-///
+/// ApiClient that wraps every other specific api
 class StreamChatApi {
-  ///
+  /// Initialize a new stream chat api
   StreamChatApi(
     String apiKey, {
     StreamHttpClient? client,
@@ -38,42 +38,42 @@ class StreamChatApi {
 
   UserApi? _user;
 
-  ///
+  /// Api dedicated to users operations
   UserApi get user => _user ??= UserApi(_client);
 
   GuestApi? _guest;
 
-  ///
+  /// Api dedicated to guest operations
   GuestApi get guest => _guest ??= GuestApi(_client);
 
   MessageApi? _message;
 
-  ///
+  /// Api dedicated to message operations
   MessageApi get message => _message ??= MessageApi(_client);
 
   ChannelApi? _channel;
 
-  ///
+  /// Api dedicated to channel operations
   ChannelApi get channel => _channel ??= ChannelApi(_client);
 
   DeviceApi? _device;
 
-  ///
+  /// Api dedicated to device operations
   DeviceApi get device => _device ??= DeviceApi(_client);
 
   ModerationApi? _moderation;
 
-  ///
+  /// Api dedicated to moderation operations
   ModerationApi get moderation => _moderation ??= ModerationApi(_client);
 
   GeneralApi? _general;
 
-  ///
+  /// Api dedicated to general operations
   GeneralApi get general => _general ??= GeneralApi(_client);
 
   AttachmentFileUploader? _fileUploader;
 
-  ///
+  /// Class responsible for uploading images and files to a given channel
   AttachmentFileUploader get fileUploader =>
       _fileUploader ??= StreamAttachmentFileUploader(_client);
 }

packages/stream_chat/lib/src/core/api/user_api.dart

@@ -6,9 +6,9 @@ import 'package:stream_chat/src/core/http/stream_http_client.dart';
 import 'package:stream_chat/src/core/models/filter.dart';
 import 'package:stream_chat/src/core/models/user.dart';
 
-///
+/// Defines the api dedicated to users operations
 class UserApi {
-  ///
+  /// Initialize a new user api
   UserApi(this._client);
 
   final StreamHttpClient _client;

packages/stream_chat/lib/src/core/http/connection_id_manager.dart

@@ -1,26 +1,26 @@
 // ignore_for_file: use_setters_to_change_properties
 
-///
+/// Handles the connection id of the websocket connection
 class ConnectionIdManager {
-  ///
+  /// Initialize a new connection id manager
   ConnectionIdManager({
     String? connectionId,
   }) : _connectionId = connectionId;
 
   String? _connectionId;
 
-  ///
+  /// Get the current connection id
   String? get connectionId => _connectionId;
 
-  ///
+  /// True if there is a connection id
   bool get hasConnectionId => _connectionId != null;
 
-  ///
+  /// Set the connection id
   void setConnectionId(String connectionId) {
     _connectionId = connectionId;
   }
 
-  ///
+  /// Clear the connection id
   void reset() {
     _connectionId = null;
   }

packages/stream_chat/lib/src/core/http/interceptor/auth_interceptor.dart

@@ -1,20 +1,20 @@
 import 'package:dio/dio.dart';
 import 'package:stream_chat/src/core/api/responses.dart';
+import 'package:stream_chat/src/core/error/error.dart';
 import 'package:stream_chat/src/core/http/stream_chat_dio_error.dart';
 import 'package:stream_chat/src/core/http/stream_http_client.dart';
 import 'package:stream_chat/src/core/http/token.dart';
-
 import 'package:stream_chat/src/core/http/token_manager.dart';
-import 'package:stream_chat/src/core/error/error.dart';
 
-///
+/// Authentication interceptor that refreshes the token if
+/// an auth error is received
 class AuthInterceptor extends Interceptor {
-  ///
+  /// Initialize a new auth interceptor
   AuthInterceptor(this._client, this._tokenManager);
 
   final StreamHttpClient _client;
 
-  ///
+  /// The token manager used in the client
   final TokenManager _tokenManager;
 
   @override

packages/stream_chat/lib/src/core/http/interceptor/connection_id_interceptor.dart

@@ -1,8 +1,7 @@
 import 'package:dio/dio.dart';
-
 import 'package:stream_chat/src/core/http/connection_id_manager.dart';
 
-///
+/// Interceptor that injects the connection id in the request params
 class ConnectionIdInterceptor extends Interceptor {
   ///
   ConnectionIdInterceptor(this.connectionIdManager);

packages/stream_chat/lib/src/core/http/interceptor/logging_interceptor.dart

@@ -5,26 +5,26 @@ import 'dart:math' as math;
 
 import 'package:dio/dio.dart';
 
-///
+/// Step where we're logging
 enum InterceptStep {
-  ///
+  /// Request
   request,
 
-  ///
+  /// Response
   response,
 
-  ///
+  /// Error
   error,
 }
 
-///
+/// Function used to print the log
 typedef LogPrint = void Function(InterceptStep step, Object object);
 
 void _defaultLogPrint(InterceptStep step, Object object) => print(object);
 
-///
+/// Interceptor dedicated to logging
 class LoggingInterceptor extends Interceptor {
-  ///
+  /// Initialize a new logging interceptor
   LoggingInterceptor({
     this.request = true,
     this.requestHeader = false,
@@ -310,13 +310,6 @@ class LoggingInterceptor extends Interceptor {
     });
   }
 
-/*  bool _canFlattenMap(Map map) =>
-      map.values.where((dynamic val) => val is Map || val is List).isEmpty &&
-      map.toString().length < maxWidth;
-
-  bool _canFlattenList(List list) =>
-      list.length < 10 && list.toString().length < maxWidth;*/
-
   void _printMapAsTable(
     void Function(Object) logPrint,
     Map? map, {

packages/stream_chat/lib/src/core/http/stream_chat_dio_error.dart

@@ -1,9 +1,9 @@
 import 'package:dio/dio.dart';
 import 'package:stream_chat/src/core/error/error.dart';
 
-///
+/// Error class specific to StreamChat and Dio
 class StreamChatDioError extends DioError {
-  ///
+  /// Initialize a stream chat dio error
   StreamChatDioError({
     required this.error,
     required RequestOptions requestOptions,

packages/stream_chat/lib/src/core/http/token.dart

@@ -5,21 +5,22 @@ import 'package:jose/jose.dart';
 import 'package:stream_chat/src/core/models/user.dart';
 import 'package:stream_chat/src/core/util/utils.dart';
 
-///
+/// A function which can be used to request a Stream Chat API token from your
+/// own backend server
 typedef GuestTokenProvider = Future<String> Function(User user);
 
-///
+/// Authentication type
 enum AuthType {
-  ///
+  /// JWT token
   jwt,
 
-  ///
+  /// Anonymous user
   anonymous,
 }
 
-///
+/// Extension for returning the AuthType as a string
 extension AuthTypeX on AuthType {
-  ///
+  /// Returns the AuthType as a string
   String get raw => {
         AuthType.jwt: 'jwt',
         AuthType.anonymous: 'anonymous',
@@ -71,13 +72,13 @@ class Token extends Equatable {
     return Token.fromRawValue(rawToken);
   }
 
-  ///
+  /// Authentication type of this token
   final AuthType authType;
 
-  ///
+  /// String value of the token
   final String rawValue;
 
-  ///
+  /// User id associated with this token
   final String userId;
 
   @override

packages/stream_chat/lib/src/core/http/token_manager.dart

@@ -1,12 +1,13 @@
 import 'package:stream_chat/src/core/http/token.dart';
 
 /// A function which can be used to request a Stream Chat API token from your
-/// own backend server. Function requires a single [userId].
+/// own backend server.
+/// Function requires a single [userId].
 typedef TokenProvider = Future<String> Function(String userId);
 
-///
+/// Handles common token operations
 class TokenManager {
-  ///
+  /// Initialize a new token manager
   TokenManager({
     String? userId,
     Token? token,
@@ -25,10 +26,10 @@ class TokenManager {
   /// User id to which this TokenManager is configured to
   String? get userId => _userId;
 
-  ///
+  /// True if it's a static token
   bool get isStatic => _type == 'static';
 
-  ///
+  /// Set a token or a token provider
   Future<Token> setTokenOrProvider(
     String userId, {
     Token? token,
@@ -58,7 +59,7 @@ class TokenManager {
     return loadToken();
   }
 
-  ///
+  /// Returns the token refreshing the existing one if [refresh] is true
   Future<Token> loadToken({bool refresh = false}) async {
     assert(
       _userId != null && _type != null,
@@ -71,7 +72,7 @@ class TokenManager {
     return _token!;
   }
 
-  ///
+  /// Resets the token manager
   void reset() {
     _userId = null;
     _token = null;