Improve the socket API documentation.

chrome/common/extensions/api/experimental_socket.idl

Index: chrome/common/extensions/api/experimental_socket.idl
diff --git a/chrome/common/extensions/api/experimental_socket.idl b/chrome/common/extensions/api/experimental_socket.idl
index bb17d763ca27f4ffc83d182dadbbe306a2d3c973..64c1917bcc0ee5b73ce735f90d7efbe9fffb762e 100644
--- a/chrome/common/extensions/api/experimental_socket.idl
+++ b/chrome/common/extensions/api/experimental_socket.idl
@@ -102,7 +102,9 @@ namespace experimental.socket {
     // |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
@@ -111,35 +113,33 @@ namespace experimental.socket {
                      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,