Updates comments

Author: kpsroka

lib/src/delayed_callback.dart

@@ -6,8 +6,8 @@ final _random = Random();
 /// Like [Future.delayed], but allows some control of the delay before the
 /// callback execution.
 final class DelayedCallback<T> {
-  // Created a socket connection attempt whose delayFuture will complete after
-  // the given delay.
+  /// Executes the provided [callback] after [delay] elapses, unless aborted
+  /// during the delay.
   DelayedCallback({
     required Duration delay,
     required Future<T> Function() callback,
@@ -28,6 +28,13 @@ final class DelayedCallback<T> {
   final Future<T> Function() _callback;
   bool _callbackRan = false;
   final _callbackCompleter = Completer<T>();
+
+  /// Returns a future that is completed with result of callback execution.
+  ///
+  /// If the callback throws, then this future completes with the thrown error.
+  ///
+  /// If the callback gets aborted before execution, the future is completed
+  /// with a custom error.
   late final Future<T> callbackFuture = _callbackCompleter.future;
 
   void _runCallback() {
@@ -44,8 +51,8 @@ final class DelayedCallback<T> {
   /// executed.
   bool get delayDone => !_delayTimer.isActive;
 
-  // Immediately skips delay and executes callback. Has no effect if the delay
-  // has expired already.
+  /// Immediately skips delay and executes callback. Has no effect if the delay
+  /// has expired already, or if the callback was aborted.
   void skipDelay() {
     if (_delayTimer.isActive) {
       _delayTimer.cancel();
@@ -55,9 +62,9 @@ final class DelayedCallback<T> {
     }
   }
 
-  // Immediately completes delay with an error. The [callbackFuture] is going
-  // to be completed with an error. Has no effect if the delay has expired
-  // already.
+  /// Aborts attempt at calling the callback. The [callbackFuture] is going to
+  /// be completed with an error. Has no effect if the delay has expired
+  /// already.
   void abort() {
     if (_delayTimer.isActive) {
       _delayTimer.cancel();

lib/src/socket.dart

@@ -115,7 +115,7 @@ class PhoenixSocket {
 
   /// Whether the phoenix socket is ready to join channels. Note that this is
   /// not the same as the WebSocketConnected state, but rather is set to true
-  /// when both web socket is connected, and the first heartbeat reply has been
+  /// when both WebSocket is connected, and the first heartbeat reply has been
   /// received.
   bool get isOpen => _isOpen;
 
@@ -140,15 +140,15 @@ class PhoenixSocket {
   /// Connects to the underlying WebSocket and prepares this PhoenixSocket for
   /// connecting to channels.
   ///
-  /// The returned future will complete as soon as the attempt to connect to a
-  /// WebSocket is scheduled. If a WebSocket is connected or connecting, then
-  /// it returns without any action.
-  ///
-  /// To check whether the socket is ready for use, use [isOpen], or await on an
-  /// event from [openStream].
+  /// The returned future will complete when a connection is established and the
+  /// first heartbeat round-trip completes.
   ///
   /// If [immediately] is set to `true` and if a connection is not established,
   /// it will attempt to connect to a socket without delay.
+  ///
+  /// If a connection is already open, then this method returns immediately. If
+  /// you want to force a new connection, use [close] with reconnect parameter
+  /// set to true.
   Future<void> connect({bool immediately = false}) async {
     if (_disposed) {
       throw StateError('PhoenixSocket cannot connect after being disposed.');

lib/src/socket_connection.dart

@@ -21,7 +21,7 @@ const forcedReconnectionRequested = 4002;
 /// necessary.
 class SocketConnectionManager {
   SocketConnectionManager({
-    required Future<WebSocketChannel> Function() factory,
+    required WebSocketChannelFactory factory,
     required List<Duration> reconnectDelays,
     required void Function(String) onMessage,
     required void Function(WebSocketConnectionState) onStateChange,
@@ -51,9 +51,11 @@ class SocketConnectionManager {
 
   bool _disposed = false;
 
-  /// Requests to start connecting to the socket. Returns a future
+  /// Requests to start connecting to the socket. Returns a future that
+  /// completes when a WebSocket connection has been established.
   ///
-  /// Has no effect if the connection is already established.
+  /// If [immediately] is false, and a connection is already established, then
+  /// this method does not have any effect.
   ///
   /// If [immediately] is set to true, then an attempt to connect is made
   /// immediately. This might result in dropping the current connection and
@@ -84,16 +86,26 @@ class SocketConnectionManager {
   /// Sends a message to the socket. Will start connecting to the socket if
   /// necessary.
   ///
-  /// Returns a future that completes when the message is successfully added to
-  /// the socket.
+  /// Returns a future that completes when the message is successfully passed to
+  /// an established WebSocket.
   ///
-  /// If after call to [addMessage] a call to [dispose] or [stop] is made, then
-  /// this future will complete with an error instead.
+  /// The future will complete with error if the message couldn't be added to
+  /// a WebSocket, either because this connection manager was disposed, or the
+  /// WebSocket could not accept messages.
   Future<void> addMessage(String message) async {
     final connection = await _maybeConnect();
     return connection.send(message);
   }
 
+  /// Forces reconnection to the WebSocket. Returns a future that completes when
+  /// a WebSocket connection has been established.
+  ///
+  /// If a connection was already established, it gets closed with the provided
+  /// code and optional reason.
+  ///
+  /// If [immediately] is true, then the new connection attempt is executed
+  /// immediately, irrespective of ordinary reconnection delays provided to the
+  /// constructor.
   Future<void> reconnect(int code, {String? reason, bool immediately = false}) {
     final currentConnection = _connectionsStream.valueOrNull;
     final connectFuture = _connect();