Improve the socket API documentation.

Improve the socket API documentation.

BUG=138255
TEST=Build


Committed: http://src.chromium.org/viewvc/chrome?view=rev&revision=147852

[Peng, 2012-07-20 19:12:01]

Hi Mike, Could you please have a look? Thanks.

[miket_OOO, 2012-07-20 19:27:43]

https://chromiumcodereview.appspot.com/10796067/diff/2001/chrome/common/exten...
File chrome/common/extensions/api/experimental_socket.idl (right):

https://chromiumcodereview.appspot.com/10796067/diff/2001/chrome/common/exten...
chrome/common/extensions/api/experimental_socket.idl:106: // caller via callback
function. Note: The given socket should be connected
Add "the" after "via."

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

https://chromiumcodereview.appspot.com/10796067/diff/2001/chrome/common/exten...
chrome/common/extensions/api/experimental_socket.idl:117: // connected by using
connect() function.
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."

https://chromiumcodereview.appspot.com/10796067/diff/2001/chrome/common/exten...
chrome/common/extensions/api/experimental_socket.idl:121: // or an error
occurred.
Match verb tenses ("occurred" is inconsistent).

https://chromiumcodereview.appspot.com/10796067/diff/2001/chrome/common/exten...
chrome/common/extensions/api/experimental_socket.idl:126: // Receive data from
the given socket. The received data and the sender's
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.

https://chromiumcodereview.appspot.com/10796067/diff/2001/chrome/common/exten...
chrome/common/extensions/api/experimental_socket.idl:131: // sender's address
without blocking.
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.

https://chromiumcodereview.appspot.com/10796067/diff/2001/chrome/common/exten...
chrome/common/extensions/api/experimental_socket.idl:136: // Send data to the
given address. The socket should be a UDP socket.
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."

https://chromiumcodereview.appspot.com/10796067/diff/2001/chrome/common/exten...
chrome/common/extensions/api/experimental_socket.idl:142: // or an error
occurred.
Match tense ("occurred").

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

https://chromiumcodereview.appspot.com/10796067/diff/2001/chrome/common/exten...
File chrome/common/extensions/api/experimental_socket.idl (right):

https://chromiumcodereview.appspot.com/10796067/diff/2001/chrome/common/exten...
chrome/common/extensions/api/experimental_socket.idl:106: // caller via callback
function. Note: The given socket should be connected
On 2012/07/20 19:27:44, miket wrote:
> Add "the" after "via."
> 
> I'm not sure this addition gives the reader any new information that wasn't
> available in the argument list.

Done

https://chromiumcodereview.appspot.com/10796067/diff/2001/chrome/common/exten...
chrome/common/extensions/api/experimental_socket.idl:117: // connected by using
connect() function.
On 2012/07/20 19:27:44, miket wrote:
> 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."

Done.

https://chromiumcodereview.appspot.com/10796067/diff/2001/chrome/common/exten...
chrome/common/extensions/api/experimental_socket.idl:121: // or an error
occurred.
On 2012/07/20 19:27:44, miket wrote:
> Match verb tenses ("occurred" is inconsistent).

Done.

https://chromiumcodereview.appspot.com/10796067/diff/2001/chrome/common/exten...
chrome/common/extensions/api/experimental_socket.idl:126: // Receive data from
the given socket. The received data and the sender's
On 2012/07/20 19:27:44, miket wrote:
> 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.

Done.

https://chromiumcodereview.appspot.com/10796067/diff/2001/chrome/common/exten...
chrome/common/extensions/api/experimental_socket.idl:131: // sender's address
without blocking.
On 2012/07/20 19:27:44, miket wrote:
> 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.

Done.

https://chromiumcodereview.appspot.com/10796067/diff/2001/chrome/common/exten...
chrome/common/extensions/api/experimental_socket.idl:136: // Send data to the
given address. The socket should be a UDP socket.
On 2012/07/20 19:27:44, miket wrote:
> 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."

Done.

https://chromiumcodereview.appspot.com/10796067/diff/2001/chrome/common/exten...
chrome/common/extensions/api/experimental_socket.idl:142: // or an error
occurred.
On 2012/07/20 19:27:44, miket wrote:
> Match tense ("occurred").

Done.

[miket_OOO, 2012-07-20 20:20:17]

I think this is much better. LGTM. On the Stack Overflow question
(http://stackoverflow.com/questions/11570382/chrome-experimental-socket-api-wh...),
I wonder whether we should also include a link or two to some documentation
about TCP/UDP socket interfaces. It sounds like it might help clear up some of
the confusion there. I don't think we should get into explaining TCP/UDP in our
own IDL documentation; we couldn't possibly do a complete job, nor could we do a
better job than existing documentation for POSIX sockets.

Thanks for the edits!

[commit-bot: I haz the power, 2012-07-23 13:57:35]

CQ is trying da patch. Follow status at
https://chromium-status.appspot.com/cq/penghuang@chromium.org/10796067/5002

[commit-bot: I haz the power, 2012-07-23 15:28:15]

Change committed as 147852