Update comments of the Pepper networking APIs.

ppapi/api/dev/ppb_udp_socket_dev.idl

Index: ppapi/api/dev/ppb_udp_socket_dev.idl
diff --git a/ppapi/api/dev/ppb_udp_socket_dev.idl b/ppapi/api/dev/ppb_udp_socket_dev.idl
index 32ad30a81b21cb64d2aac5a93aa604447ccca020..3db47982896554593f6cc2e5fd9e10d36cc6a43f 100644
--- a/ppapi/api/dev/ppb_udp_socket_dev.idl
+++ b/ppapi/api/dev/ppb_udp_socket_dev.idl
@@ -5,7 +5,6 @@
 
 /**
  * This file defines the <code>PPB_UDPSocket_Dev</code> interface.
- * TODO(yzshen): Tidy up the document.
  */
 
 [generate_thunk]
@@ -14,61 +13,126 @@ label Chrome {
   M29 = 0.1
 };
 
+/**
+ * Option types used by <code>SetOption()</code>.
+ */
 [assert_size(4)]
 enum PP_UDPSocket_Option_Dev {
-  // Allows the socket to share the local address to which it will be bound with
-  // other processes. Value's type should be PP_VARTYPE_BOOL.
+  /**
+   * Allows the socket to share the local address to which it will be bound with
+   * other processes. Value's type should be <code>PP_VARTYPE_BOOL</code>.
+   * This option can only be set before calling <code>Bind()</code>.
+   */
   PP_UDPSOCKET_OPTION_ADDRESS_REUSE = 0,
 
-  // Allows sending and receiving packets to and from broadcast addresses.
-  // Value's type should be PP_VARTYPE_BOOL.
+  /**
+   * Allows sending and receiving packets to and from broadcast addresses.
+   * Value's type should be <code>PP_VARTYPE_BOOL</code>.
+   * This option can only be set before calling <code>Bind()</code>.
+   */
   PP_UDPSOCKET_OPTION_BROADCAST = 1,
 
-  // Specifies the total per-socket buffer space reserved for sends. 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 it will conform to it.
+  /**
+   * Specifies the total per-socket buffer space reserved for sends. Value's
+   * type should be <code>PP_VARTYPE_INT32</code>.
+   * This option can only be set after a successful <code>Bind()</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 it will conform to it.
+   */
   PP_UDPSOCKET_OPTION_SEND_BUFFER_SIZE = 2,
 
-  // Specifies the total per-socket buffer space reserved for receives. 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 it will conform to it.
+  /**
+   * Specifies the total per-socket buffer space reserved for receives. Value's
+   * type should be <code>PP_VARTYPE_INT32</code>.
+   * This option can only be set after a successful <code>Bind()</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 it will conform to it.
+   */
   PP_UDPSOCKET_OPTION_RECV_BUFFER_SIZE = 3
 };
 
+/**
+ * The <code>PPB_UDPSocket_Dev</code> interface provides UDP socket operations.
+ *
+ * Permissions: Apps permission <code>socket</code> with subrule
+ * <code>udp-bind</code> is required for <code>Bind()</code>; subrule
+ * <code>udp-send-to</code> is required for <code>SendTo()</code>.
+ * For more details about network communication permissions, please see:
+ * http://developer.chrome.com/apps/app_network.html
+ */
 interface PPB_UDPSocket_Dev {
   /**
    * Creates a UDP 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 UDP socket or 0
+   * on failure.
    */
   PP_Resource Create([in] PP_Instance instance);
 
   /**
    * Determines if a given resource is a UDP socket.
+   *
+   * @param[in] resource A <code>PP_Resource</code> to check.
+   *
+   * @return <code>PP_TRUE</code> if the input is a
+   * <code>PPB_UDPSocket_Dev</code> resource; <code>PP_FALSE</code>
+   * otherwise.
    */
   PP_Bool IsUDPSocket([in] PP_Resource resource);
 
   /**
-   * Binds to the address given by |addr|, which is a PPB_NetAddress_Dev
-   * resource.
+   * Binds to the given address.

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

s/Binds/Binds the socket/

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

Done.

+   *
+   * @param[in] udp_socket A <code>PP_Resource</code> corresponding to a UDP
+   * 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>.
+   * <code>PP_ERROR_NOACCESS</code> will be returned if the caller doesn't have
+   * required permissions. <code>PP_ERROR_ADDRESS_IN_USE</code> will be returned
+   * if the address is already in use.
    */
   int32_t Bind([in] PP_Resource udp_socket,
                [in] PP_Resource addr,
                [in] PP_CompletionCallback callback);
 
   /**
-   * Returns the address that the socket has bound to, as a PPB_NetAddress_Dev
-   * resource.  Bind must be called and succeed first. Returns 0 if Bind fails,
-   * or if Close has been called.
+   * Get the address that the socket has bound to. It can only be called after

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

s/Get/Gets

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

Done.

+   * a successful <code>Bind()</code> call.
+   *
+   * @param[in] udp_socket A <code>PP_Resource</code> corresponding to a UDP
+   * socket.
+   *
+   * @return A <code>PPB_NetAddress_Dev</code> resource on success or 0 on
+   * failure.
    */
   PP_Resource GetBoundAddress([in] PP_Resource udp_socket);
 
   /**
-   * Performs a non-blocking recvfrom call on socket.
-   * Bind must be called first. |callback| is invoked when recvfrom reads data.
-   * |addr| will store a PPB_NetAddress_Dev resource on success.
+   * Receives data from the socket and stores the source address. It can only be
+   * called after a successful <code>Bind()</code> call.
+   *
+   * @param[in] udp_socket A <code>PP_Resource</code> corresponding to a UDP
+   * socket.
+   * @param[out] buffer The buffer to store the received data on success. It
+   * must be at least as large as <code>num_bytes</code>.
+   * @param[in] num_bytes The number of bytes to read.

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

s/read/receive to be consistent with 'Receives' above and 'received' below.

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

Done.

+   * @param[out] addr A <code>PPB_NetAddress_Dev</code> resource to store the
+   * source address on success.
+   * @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 received; otherwise, an error code from <code>pp_errors.h</code>.
    */
   int32_t RecvFrom([in] PP_Resource udp_socket,
                    [out] str_t buffer,
@@ -77,9 +141,22 @@ interface PPB_UDPSocket_Dev {
                    [in] PP_CompletionCallback callback);
 
   /**
-   * Performs a non-blocking sendto call on the socket.
-   * Bind must be called first. |addr| is a PPB_NetAddress_Dev resource holding
-   * the target address. |callback| is invoked when sendto completes.
+   * Sends data to a specific destination. It can only be called after a

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

s/destination/target address
or change 'target address' below to 'destination address'.

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

Done.

+   * successful <code>Bind()</code> call.
+   *
+   * @param[in] udp_socket A <code>PP_Resource</code> corresponding to a UDP
+   * socket.
+   * @param[in] buffer The buffer containing the data to send.
+   * @param[in] num_bytes The number of bytes to send.
+   * @param[in] addr A <code>PPB_NetAddress_Dev</code> resource holding the
+   * target address.
+   * @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 sent; otherwise, an error code from <code>pp_errors.h</code>.
+   * <code>PP_ERROR_NOACCESS</code> will be returned if the caller doesn't have
+   * required permissions.
    */
   int32_t SendTo([in] PP_Resource udp_socket,
                  [in] str_t buffer,
@@ -88,17 +165,33 @@ interface PPB_UDPSocket_Dev {
                  [in] PP_CompletionCallback callback);
 
   /**
-   * Cancels all pending reads and writes, and closes the socket.
+   * Cancels all pending reads and writes, and closes the socket. Any pending
+   * callbacks will still run, reporting <code>PP_ERROR_ABORTED</code> if
+   * pending IO was interrupted. After a call to this method, any output

[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>RecvFrom()</code> calls will be accessed.

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

Because the output parameters also include PP_Resource pointers, I changed the
sentence to "no output parameters passed into..."

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

+   * parameters passed into previous <code>RecvFrom()</code> calls won't be
+   * accessed. It is not valid to call <code>Bind()</code> again.
+   *
+   * The socket is implicitly closed if it is destroyed, so you are not
+   * required to call this method.
+   *
+   * @param[in] udp_socket A <code>PP_Resource</code> corresponding to a UDP
+   * socket.
    */
   void Close([in] PP_Resource udp_socket);
 
   /**
-   * Sets a socket option to |udp_socket|. Should be called before Bind().
-   * See the PP_UDPSocket_Option_Dev description for option names, value types
-   * and allowed values.
-   * Returns PP_OK on success. Otherwise, returns PP_ERROR_BADRESOURCE (if bad
-   * |udp_socket| provided), PP_ERROR_BADARGUMENT (if bad name/value/value's
-   * type provided) or PP_ERROR_FAILED in the case of internal errors.
+   * Sets a socket option on the UDP socket.
+   * Please see the <code>PP_UDPSocket_Option_Dev</code> description for option
+   * names, value types and allowed values.
+   *
+   * @param[in] udp_socket A <code>PP_Resource</code> corresponding to a UDP
+   * 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 udp_socket,
                     [in] PP_UDPSocket_Option_Dev name,