[IO] Improve documentation for dart:io Socket.onWrite.

runtime/bin/socket.dart

Index: runtime/bin/socket.dart
diff --git a/runtime/bin/socket.dart b/runtime/bin/socket.dart
index 6c1b49de72023eb589f700e411cf0b33e570d452..e26694d0b5ea03deaf0acdddea08efbabaf1a959 100644
--- a/runtime/bin/socket.dart
+++ b/runtime/bin/socket.dart
@@ -74,8 +74,10 @@ interface Socket extends Hashable default _Socket {
   void set onData(void callback());
 
   /**
-   * The write handler gets called when the socket becomes available for
-   * writing.
+   * The write handler gets called once when the socket becomes
+   * available for writing. Then the handler is automatically reset to null.
+   * This handler is mainly used when writeList has reported an incomplete
+   * write, to schedule writing the remaining data to the socket.
    */
   void set onWrite(void callback());