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 84 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 socket. The received data will be delivered to
+    // caller via callback function. Note: The given socket should be connected

[miket_OOO, 2012/07/20 19:27:44]

Add "the" after "via."

I'm not sure this addition gives the reader any new information that wasn't
available in the argument list.

[Peng, 2012/07/20 20:06:39]

Done

+    // by using connect() function.
     // |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 socket. Note: The given socket should be
+    // connected by using connect() function.

[miket_OOO, 2012/07/20 19:27:44]

Same comment as above. This addition is superfluous. If you really want to tell
the reader that only connected sockets can read/write data, then a sufficient
hint would be "Writes data on the given connected socket."

[Peng, 2012/07/20 20:06:39]

Done.

     // |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 occurred.

[miket_OOO, 2012/07/20 19:27:44]

Match verb tenses ("occurred" is inconsistent).

[Peng, 2012/07/20 20:06:39]

Done.

     static void write(long socketId,
                       ArrayBuffer data,
                       WriteCallback callback);
 
-    // Reads data from the given socket.
+    // Receive data from the given socket. The received data and the sender's

[miket_OOO, 2012/07/20 19:27:44]

Match voice ("Receive" is inconsistent).

The added sentence doesn't add any new information. The reader can already
figure out that RecvFromCallback has a RecvFromInfo argument, which is
self-documenting.

Alternatively, if you think that the sentence is important, it's better placed
as documentation to RecvFromInfo, where the reader can see the actual
data/address fields.

[Peng, 2012/07/20 20:06:39]

Done.

+    // address will be delivered to caller via callback function.
     // |socketId| : The socketId.
     // |bufferSize| : The receive buffer size.
-    // |callback| : Delivers data that was available to be read without
-    // blocking.
+    // |callback| : Delivers data that was available to be read and
+    // sender's address without blocking.

[miket_OOO, 2012/07/20 19:27:44]

Same comment as above -- I'd change this to something like "Returns result of
recvFrom operation" rather than imprecisely duplicating a subset of the
information returned in RecvFromCallback.

[Peng, 2012/07/20 20:06:39]

Done.

     static void recvFrom(long socketId,
                          optional long bufferSize,
                          RecvFromCallback callback);
 
-    // Writes data on the given socket.
+    // Send data to the given address. The socket should be a UDP socket.

[miket_OOO, 2012/07/20 19:27:44]

Match voice ("Send" is inconsistent).

It would be more precise and concise to say "Sends data on the given UDP socket
to the given address and port."

[Peng, 2012/07/20 20:06:39]

Done.

     // |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 occurred.

[miket_OOO, 2012/07/20 19:27:44]

Match tense ("occurred").

[Peng, 2012/07/20 20:06:39]

Done.

     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);
   };
 
 };