Mention ready in the docs for connect (#287)

Closes #280 There can be confusion when there are errors creating the channel because the only wait to catch them is to include an `await channel.ready` in the try block. Mention that `ready` can complete as an error in the case of connection failure.
dart-lang · Oct 6, 2023 · f3ac1bf · f3ac1bf
1 parent 364013d
commit f3ac1bf
Show file tree

Hide file tree

Showing 3 changed files with 9 additions and 2 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,8 +1,9 @@
-## 2.4.1
+## 2.4.1-wip
 
 - Update the examples to use `WebSocketChannel.ready` and clarify that
   `WebSocketChannel.ready` should be awaited before sending data over the
   `WebSocketChannel`.
+- Mention `ready` in the docs for `connect`.
 
 ## 2.4.0
 

diff --git a/lib/src/channel.dart b/lib/src/channel.dart
@@ -134,6 +134,12 @@ class WebSocketChannel extends StreamChannelMixin {
   /// communicate over the resulting socket.
   ///
   /// The optional [protocols] parameter is the same as `WebSocket.connect`.
+  ///
+  /// A WebSocketChannel is returned synchronously, however the connection is
+  /// not established synchronously.
+  /// The [ready] future will complete after the channel is connected.
+  /// If there are errors creating the connection the [ready] future will
+  /// complete with an error.
   factory WebSocketChannel.connect(Uri uri, {Iterable<String>? protocols}) =>
       platform.connect(uri, protocols: protocols);
 }

diff --git a/pubspec.yaml b/pubspec.yaml
@@ -1,5 +1,5 @@
 name: web_socket_channel
-version: 2.4.1
+version: 2.4.1-wip
 
 description: >-
   StreamChannel wrappers for WebSockets. Provides a cross-platform