Improve the socket API documentation.

chrome/common/extensions/api/experimental_socket.idl

 // Copyright (c) 2012 The Chromium Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
 // File-level comment to appease parser. Eventually this will not be necessary.
 
 namespace experimental.socket {
   enum SocketType {
     tcp,
     udp
@@ skipping 27 matching lines @@
   callback ReadCallback = void (ReadInfo readInfo);
 
   dictionary WriteInfo {
     // The number of bytes sent, or a negative error code.
     long bytesWritten;
   };
 
   callback WriteCallback = void (WriteInfo writeInfo);
 
   dictionary RecvFromInfo {
-    // The resultCode returned from the underlying read() call.
+    // The resultCode returned from the underlying recvfrom() call.
     long resultCode;
 
     ArrayBuffer data;
+
+    // The address of the remote machine.
     DOMString address;
+
     long port;
   };
 
   callback RecvFromCallback = void (RecvFromInfo recvFromInfo);
 
   callback SendToCallback = void (WriteInfo writeInfo);
 
   callback SetKeepAliveCallback = void (boolean result);
 
   callback SetNoDelayCallback = void (boolean result);
@@ skipping 32 matching lines @@
     static void bind(long socketId,
                      DOMString address,
                      long port,
                      BindCallback callback);
 
     // Disconnects the socket. For UDP sockets, <code>disconnect</code> is a
     // non-operation but is safe to call.
     // |socketId| : The socketId.
     static void disconnect(long socketId);
 
-    // Reads data from the given socket.
+    // Reads data from the given connected socket.
     // |socketId| : The socketId.
     // |bufferSize| : The read buffer size.
     // |callback| : Delivers data that was available to be read without
     // blocking.
     static void read(long socketId,
                      optional long bufferSize,
                      ReadCallback callback);
 
-    // Writes data on the given socket.
+    // Writes data on the given connected socket.
     // |socketId| : The socketId.
     // |data| : The data to write.
-    // |callback| : Called when the first of any of the following happens: the
-    // write operation completes without blocking, the write operation blocked
-    // before completion (in which case onEvent() will eventually be called with
-    // a <code>writeComplete</code> event), or an error occurred.
+    // |callback| : Called when the write operation completes without blocking
+    // or an error occurs.
     static void write(long socketId,
                       ArrayBuffer data,
                       WriteCallback callback);
 
-    // Reads data from the given socket.
+    // Receives data from the given UDP socket.
     // |socketId| : The socketId.
     // |bufferSize| : The receive buffer size.
-    // |callback| : Delivers data that was available to be read without
-    // blocking.
+    // |callback| : Returns result of the recvFrom operation.
     static void recvFrom(long socketId,
                          optional long bufferSize,
                          RecvFromCallback callback);
 
-    // Writes data on the given socket.
+    // Sends data on the given UDP socket to the given address and port.
     // |socketId| : The socketId.
     // |data| : The data to write.
     // |address| : The address of the remote machine.
     // |port| : The port of the remote machine.
-    // |callback| : Called when the first of any of the following happens: the
-    // write operation completes without blocking, the write operation blocked
-    // before completion (in which case onEvent() will eventually be called with
-    // a <code>writeComplete</code> event), or an error occurred.
+    // |callback| : Called when the send operation completes without blocking
+    // or an error occurs.
     static void sendTo(long socketId,
                        ArrayBuffer data,
                        DOMString address,
                        long port,
                        SendToCallback callback);
 
     // Enable/disable keep-alive functionality for a TCP connection.
     // |socketId| : The socketId.
     // |enable| : If true, enable keep-alive functionality.
     // |delay| : Set the delay seconds between the last data packet received
     // and the first keepalive probe. Default is 0.
     // |callback| : Called when the setKeepAlive attempt is complete.
     static void setKeepAlive(long socketId,
                              boolean enable,
                              optional long delay,
                              SetKeepAliveCallback callback);
 
     // Enable/disable Nagle algorithm.
     // |socketId| : The socketId.
     // |noDelay| : If true, disable Nagle algorithm.
     // |callback| : Called when the setNoDelay attempt is complete.
     static void setNoDelay(long socketId,
                            boolean noDelay,
                            SetNoDelayCallback callback);
   };
 
 };