Make it more clear how `WebSocketChannel.ready` should be used. (dart-lang/web_socket_channel#272)

diff --git a/pkgs/web_socket_channel/CHANGELOG.md b/pkgs/web_socket_channel/CHANGELOG.md
index f8d64f1..131c0a8 100644
--- a/pkgs/web_socket_channel/CHANGELOG.md
+++ b/pkgs/web_socket_channel/CHANGELOG.md

@@ -1,3 +1,9 @@
+## 2.4.1
+
+- Update the examples to use `WebSocketChannel.ready` and clarify that
+  `WebSocketChannel.ready` should be awaited before sending data over the
+  `WebSocketChannel`.
+
 ## 2.4.0
 
 - Add a `customClient` parameter to the `IOWebSocketChannel.connect` factory,

diff --git a/pkgs/web_socket_channel/README.md b/pkgs/web_socket_channel/README.md
index 19365df..4f78db9 100644
--- a/pkgs/web_socket_channel/README.md
+++ b/pkgs/web_socket_channel/README.md

@@ -24,8 +24,10 @@
 import 'package:web_socket_channel/status.dart' as status;
 
 main() async {
-  final wsUrl = Uri.parse('ws://localhost:1234')
-  var channel = WebSocketChannel.connect(wsUrl);
+  final wsUrl = Uri.parse('ws://example.com')
+  final channel = WebSocketChannel.connect(wsUrl);
+
+  await channel.ready;
 
   channel.stream.listen((message) {
     channel.sink.add('received!');

diff --git a/pkgs/web_socket_channel/example/example.dart b/pkgs/web_socket_channel/example/example.dart
index e3a1505..b09b798 100644
--- a/pkgs/web_socket_channel/example/example.dart
+++ b/pkgs/web_socket_channel/example/example.dart

@@ -2,11 +2,14 @@
 // for details. All rights reserved. Use of this source code is governed by a
 // BSD-style license that can be found in the LICENSE file.
 
-import 'package:web_socket_channel/io.dart';
 import 'package:web_socket_channel/status.dart' as status;
+import 'package:web_socket_channel/web_socket_channel.dart';
 
-void main() {
-  final channel = IOWebSocketChannel.connect('ws://localhost:1234');
+void main() async {
+  final wsUrl = Uri.parse('ws://example.com');
+  final channel = WebSocketChannel.connect(wsUrl);
+
+  await channel.ready;
 
   channel.stream.listen((message) {
     channel.sink.add('received!');

diff --git a/pkgs/web_socket_channel/lib/src/channel.dart b/pkgs/web_socket_channel/lib/src/channel.dart
index 2781972..8f40d75 100644
--- a/pkgs/web_socket_channel/lib/src/channel.dart
+++ b/pkgs/web_socket_channel/lib/src/channel.dart

@@ -51,8 +51,31 @@
   /// Before the connection has been closed, this will be `null`.
   String? get closeReason => _webSocket.closeReason;
 
-  /// Future indicating if the connection has been established.
-  /// It completes on successful connection to the websocket.
+  /// A future that will complete when the WebSocket connection has been
+  /// established.
+  ///
+  /// This future must be complete before before data can be sent using
+  /// [WebSocketChannel.sink].
+  ///
+  /// If a connection could not be established (e.g. because of a network
+  /// issue), then this future will complete with an error.
+  ///
+  /// For example:
+  /// ```
+  /// final channel = WebSocketChannel.connect(Uri.parse('ws://example.com'));
+  ///
+  /// try {
+  ///   await channel.ready;
+  /// } on SocketException catch (e) {
+  ///   // Handle the exception.
+  /// } on WebSocketChannelException catch (e) {
+  ///   // Handle the exception.
+  /// }
+  ///
+  /// // If `ready` completes without an error then the channel is ready to
+  /// // send data.
+  /// channel.sink.add('Hello World');
+  /// ```
   final Future<void> ready = Future.value();
 
   @override

diff --git a/pkgs/web_socket_channel/pubspec.yaml b/pkgs/web_socket_channel/pubspec.yaml
index 71b28e1..79be718 100644
--- a/pkgs/web_socket_channel/pubspec.yaml
+++ b/pkgs/web_socket_channel/pubspec.yaml

@@ -1,5 +1,5 @@
 name: web_socket_channel
-version: 2.4.0
+version: 2.4.1
 
 description: >-
   StreamChannel wrappers for WebSockets. Provides a cross-platform