Mention ready in the docs for connect (dart-archive/web_socket_channel#287)

Closes dart-lang/web_socket_channel#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.

Author: natebosch

pkgs/web_socket_channel/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
 

pkgs/web_socket_channel/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);
 }

pkgs/web_socket_channel/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