Update comments of the Pepper networking APIs.

ppapi/api/dev/ppb_tcp_socket_dev.idl

Index: ppapi/api/dev/ppb_tcp_socket_dev.idl
diff --git a/ppapi/api/dev/ppb_tcp_socket_dev.idl b/ppapi/api/dev/ppb_tcp_socket_dev.idl
index dfc038ad1dbc650667e195bd4ebefd4877fc0280..44c9d0724ff11dfe39b7fe49ca4e6055eb3a3028 100644
--- a/ppapi/api/dev/ppb_tcp_socket_dev.idl
+++ b/ppapi/api/dev/ppb_tcp_socket_dev.idl
@@ -13,44 +13,92 @@ label Chrome {
   M29 = 0.1
 };
 
+/**
+ * Option types used by <code>SetOption()</code>.

[bbudge, 2013/06/20 17:38:27]

s/types/names

[yzshen1, 2013/06/20 20:27:45]

Done.

+ */
 [assert_size(4)]
 enum PP_TCPSocket_Option_Dev {
-  // Disables coalescing of small writes to make TCP segments, and instead
-  // deliver data immediately. Value type is PP_VARTYPE_BOOL.
+  /**
+   * Disables coalescing of small writes to make TCP segments, and instead

[bbudge, 2013/06/20 17:38:27]

s/Disables/Disable
this is to match 'deliver' later on.

[yzshen1, 2013/06/20 20:27:45]

May I change 'deliver' to 'delivers'?
We usually use third-person singular for comments (such as line 29 'specifies').

On 2013/06/20 17:38:27, bbudge1 wrote:

[bbudge, 2013/06/20 21:02:32]

OK

+   * deliver data immediately. Value type is <code>PP_VARTYPE_BOOL</code>.

[bbudge, 2013/06/20 17:38:27]

s/Value type is/Value's type should be
to match UDP docs.

[yzshen1, 2013/06/20 20:27:45]

Done.

+   * This option can only be set after a successful <code>Connect()</code> call.
+   */
   PP_TCPSOCKET_OPTION_NO_DELAY = 0,
 
-  // Specifies the socket send buffer in bytes. Value's type should be
-  // PP_VARTYPE_INT32.
-  // Note: This is only treated as a hint for the browser to set the buffer
-  // size. Even if SetOption() reports that this option has been successfully
-  // set, the browser doesn't guarantee to conform to it.
+  /**
+   * Specifies the socket send buffer in bytes. Value's type should be

[bbudge, 2013/06/20 17:38:27]

nit s/buffer/buffer size
Here and below. Or better, why not copy the comment from the UDP flag
definitions.

[yzshen1, 2013/06/20 20:27:45]

Done.

+   * <code>PP_VARTYPE_INT32</code>.
+   * This option can only be set after a successful <code>Connect()</code> call.
+   *
+   * Note: This is only treated as a hint for the browser to set the buffer
+   * size. Even if <code>SetOption()</code> reports that this option has been
+   * successfully set, the browser doesn't guarantee to conform to it.

[bbudge, 2013/06/20 17:38:27]

s/to/it will

[yzshen1, 2013/06/20 20:27:45]

Done.

+   */
   PP_TCPSOCKET_OPTION_SEND_BUFFER_SIZE = 1,
 
-  // Specifies the socket receive buffer in bytes. Value's type should be
-  // PP_VARTYPE_INT32.
-  // Note: This is only treated as a hint for the browser to set the buffer
-  // size. Even if SetOption() reports that this option has been successfully
-  // set, the browser doesn't guarantee to conform to it.
+  /**
+   * Specifies the socket receive buffer in bytes. Value's type should be
+   * <code>PP_VARTYPE_INT32</code>.
+   * This option can only be set after a successful <code>Connect()</code> call.
+   *
+   * Note: This is only treated as a hint for the browser to set the buffer
+   * size. Even if <code>SetOption()</code> reports that this option has been
+   * successfully set, the browser doesn't guarantee to conform to it.

[bbudge, 2013/06/20 17:38:27]

s/to/it will

[yzshen1, 2013/06/20 20:27:45]

Done.

+   */
   PP_TCPSOCKET_OPTION_RECV_BUFFER_SIZE = 2
 };
 
 /**
  * The <code>PPB_TCPSocket_Dev</code> interface provides TCP socket operations.
+ *
+ * Permissions: Apps permission <code>socket</code> with subrule
+ * <code>tcp-connect</code> is required for <code>Connect()</code>.
+ * For more details about network communication permissions, please see:
+ * http://developer.chrome.com/apps/app_network.html
  */
 interface PPB_TCPSocket_Dev {
   /**
-   * Allocates a TCP socket resource.
+   * Creates a TCP socket resource.
+   *
+   * @param[in] instance A <code>PP_Instance</code> identifying one instance of
+   * a module.
+   *
+   * @return A <code>PP_Resource</code> corresponding to a TCP socket or 0
+   * on failure.
    */
   PP_Resource Create([in] PP_Instance instance);
 
   /**
-   * Determines if a given resource is TCP socket.
+   * Determines if a given resource is a TCP socket.
+   *
+   * @param[in] resource A <code>PP_Resource</code> to check.
+   *
+   * @return <code>PP_TRUE</code> if the input is a
+   * <code>PPB_TCPSocket_Dev</code> resource; <code>PP_FALSE</code>
+   * otherwise.
    */
   PP_Bool IsTCPSocket([in] PP_Resource resource);
 
   /**
-   * Connects to an address given by |addr|, which is a PPB_NetAddress_Dev
-   * resource.
+   * Connects to the given address.
+   *
+   * @param[in] tcp_socket A <code>PP_Resource</code> corresponding to a TCP
+   * socket.
+   * @param[in] addr A <code>PPB_NetAddress_Dev</code> resource.
+   * @param[in] callback A <code>PP_CompletionCallback</code> to be called upon
+   * completion.
+   *
+   * @return An int32_t containing an error code from <code>pp_errors.h</code>,
+   * including (but not limited to):
+   * - <code>PP_ERROR_NOACCESS</code>: the caller doesn't have required
+   *   permissions.
+   * - <code>PP_ERROR_ADDRESS_UNREACHABLE</code>: <code>addr</code> is
+   *   unreachable.
+   * - <code>PP_ERROR_CONNECTION_REFUSED</code>: the connection attempt was
+   *   refused.
+   * - <code>PP_ERROR_CONNECTION_FAILED</code>: the connection attempt failed.
+   * - <code>PP_ERROR_CONNECTION_TIMEDOUT</code>: the connection attempt timed
+   *   out.
    */
   int32_t Connect([in] PP_Resource tcp_socket,
                   [in] PP_Resource addr,
@@ -58,23 +106,41 @@ interface PPB_TCPSocket_Dev {
 
   /**
    * Gets the local address of the socket, if it has been connected.
-   * Returns a PPB_NetAddress_Dev resource on success; returns 0 on failure.
+   *
+   * @param[in] tcp_socket A <code>PP_Resource</code> corresponding to a TCP
+   * socket.
+   *
+   * @return A <code>PPB_NetAddress_Dev</code> resource on success or 0 on
+   * failure.
    */
   PP_Resource GetLocalAddress([in] PP_Resource tcp_socket);
 
   /**
    * Gets the remote address of the socket, if it has been connected.
-   * Returns a PPB_NetAddress_Dev resource on success; returns 0 on failure.
+   *
+   * @param[in] tcp_socket A <code>PP_Resource</code> corresponding to a TCP
+   * socket.
+   *
+   * @return A <code>PPB_NetAddress_Dev</code> resource on success or 0 on
+   * failure.
    */
   PP_Resource GetRemoteAddress([in] PP_Resource tcp_socket);
 
   /**
-   * Reads data from the socket. The size of |buffer| must be at least as large
-   * as |bytes_to_read|. May perform a partial read. Returns the number of bytes
-   * read or an error code. If the return value is 0, then it indicates that
-   * end-of-file was reached.
+   * Reads data from the socket. It can only be called after a successful

[bbudge, 2013/06/20 17:38:27]

s/It can/It should
because you can call it, but it would fail.

[yzshen1, 2013/06/20 20:27:45]

I have changed to "the socket must be connected" as we discussed.

On 2013/06/20 17:38:27, bbudge1 wrote:

+   * <code>Connect()</code> call. It may perform a partial read.
    *
-   * Multiple outstanding read requests are not supported.
+   * @param[in] tcp_socket A <code>PP_Resource</code> corresponding to a TCP
+   * socket.
+   * @param[out] buffer The buffer to store the received data on success. It
+   * must be at least as large as <code>bytes_to_read</code>.
+   * @param[in] bytes_to_read The number of bytes to read.
+   * @param[in] callback A <code>PP_CompletionCallback</code> to be called upon
+   * completion.
+   *
+   * @return A non-negative number on success to indicate how many bytes have
+   * been read, 0 means that end-of-file was reached; otherwise, an error code
+   * from <code>pp_errors.h</code>.
    */
   int32_t Read([in] PP_Resource tcp_socket,
                [out] str_t buffer,
@@ -82,10 +148,18 @@ interface PPB_TCPSocket_Dev {
                [in] PP_CompletionCallback callback);
 
   /**
-   * Writes data to the socket. May perform a partial write. Returns the number
-   * of bytes written or an error code.
+   * Writes data to the socket. It can only be called after a successful

[bbudge, 2013/06/20 17:38:27]

s/It can/It should

[yzshen1, 2013/06/20 20:27:45]

I have changed to "the socket must be connected" as we discussed.
On 2013/06/20 17:38:27, bbudge1 wrote:

+   * <code>Connect()</code> call. It may perform a partial write.
+   *
+   * @param[in] tcp_socket A <code>PP_Resource</code> corresponding to a TCP
+   * socket.
+   * @param[in] buffer The buffer containing the data to write.
+   * @param[in] bytes_to_write The number of bytes to write.
+   * @param[in] callback A <code>PP_CompletionCallback</code> to be called upon
+   * completion.
    *
-   * Multiple outstanding write requests are not supported.
+   * @return A non-negative number on success to indicate how many bytes have
+   * been written; otherwise, an error code from <code>pp_errors.h</code>.
    */
   int32_t Write([in] PP_Resource tcp_socket,
                 [in] str_t buffer,
@@ -93,20 +167,33 @@ interface PPB_TCPSocket_Dev {
                 [in] PP_CompletionCallback callback);
 
   /**
-   * Cancels any IO that may be pending, and disconnects the socket. Any pending
-   * callbacks will still run, reporting PP_ERROR_ABORTED if pending IO was
-   * interrupted. It is NOT valid to call Connect() again after a call to this
-   * method. Note: If the socket is destroyed when it is still connected, then
-   * it will be implicitly disconnected, so you are not required to call this
-   * method.
+   * Cancels all pending reads and writes, disconnects the socket. Any pending

[bbudge, 2013/06/20 17:38:27]

s/,/and

[yzshen1, 2013/06/20 20:27:45]

Done.

+   * callbacks will still run, reporting <code>PP_ERROR_ABORTED</code> if
+   * pending IO was interrupted. After a call to this method, any output buffers

[bbudge, 2013/06/20 17:38:27]

A little awkward. How about:
After a call to this method, no output buffer pointers passed into previous
<code>Read()</code> calls will be accessed.

[yzshen1, 2013/06/20 20:27:45]

yeah, it sounds much better. Thanks!
On 2013/06/20 17:38:27, bbudge1 wrote:

+   * passed into previous <code>Read()</code> calls won't be accessed. It is
+   * not valid to call <code>Connect()</code> again.
+   *
+   * The socket is implicitly closed if it is destroyed, so you are not required
+   * to call this method.
+   *
+   * @param[in] tcp_socket A <code>PP_Resource</code> corresponding to a TCP
+   * socket.
    */
   void Close([in] PP_Resource tcp_socket);
 
   /**
-   * Sets an option on |tcp_socket|.  Supported |name| and |value| parameters
-   * are as described for PP_TCPSocketOption_Dev.  |callback| will be
-   * invoked with PP_OK if setting the option succeeds, or an error code
-   * otherwise. The socket must be connected before SetOption is called.
+   * Sets a socket option on the TCP socket.
+   * Please see the <code>PP_TCPSocket_Option_Dev</code> description for option
+   * names, value types and allowed values.
+   *
+   * @param[in] tcp_socket A <code>PP_Resource</code> corresponding to a TCP
+   * socket.
+   * @param[in] name The option type to set.
+   * @param[in] value The option value to set.
+   * @param[in] callback A <code>PP_CompletionCallback</code> to be called upon
+   * completion.
+   *
+   * @return An int32_t containing an error code from <code>pp_errors.h</code>.
    */
   int32_t SetOption([in] PP_Resource tcp_socket,
                     [in] PP_TCPSocket_Option_Dev name,