Update comments of the Pepper networking APIs.

The following APIs are updated:
- PPB_NetAddress_Dev
- PPB_HostResolver_Dev
- PPB_TCPSocket_Dev
- PPB_UDPSocket_Dev

BUG=247225
TEST=None

Review URL: https://chromiumcodereview.appspot.com/16938011

git-svn-id: svn://svn.chromium.org/chrome/trunk/src@208037 0039d316-1c4b-4281-b951-d872f2087c98

13 files changed, 1125 insertions, 208 deletions

diff --git a/ppapi/api/dev/ppb_host_resolver_dev.idl b/ppapi/api/dev/ppb_host_resolver_dev.idl
index 9b3dfd0..fa5612b 100644
--- a/ppapi/api/dev/ppb_host_resolver_dev.idl
+++ b/ppapi/api/dev/ppb_host_resolver_dev.idl
@@ -5,7 +5,6 @@
 
 /**
  * This file defines the <code>PPB_HostResolver_Dev</code> interface.
- * TODO(yzshen): Tidy up the document.
  */
 
 [generate_thunk]
@@ -15,40 +14,85 @@ label Chrome {
 };
 
 /**
- * The <code>PP_HostResolver_Flags_Dev</code> is an enumeration of the
- * different types of flags, that can be OR-ed and passed to host
- * resolver. Currently there is only one flag defined.
+ * <code>PP_HostResolver_Flags_Dev</code> is an enumeration of flags which can
+ * be OR-ed and passed to the host resolver. Currently there is only one flag
+ * defined.
  */
 [assert_size(4)]
 enum PP_HostResolver_Flags_Dev {
   /**
-   * AI_CANONNAME
+   * Hint to request the canonical name of the host, which can be retrieved by
+   * <code>GetCanonicalName()</code>.
    */
   PP_HOSTRESOLVER_FLAGS_CANONNAME = 1 << 0
 };
 
+/**
+ * <code>PP_HostResolver_Hint_Dev</code> represents hints for host resolution.
+ */
 [assert_size(8)]
 struct PP_HostResolver_Hint_Dev {
+  /**
+   * Network address family.
+   */
   PP_NetAddress_Family_Dev family;
+  /**
+   * Combination of flags from <code>PP_HostResolver_Flags_Dev</code>.
+   */
   int32_t flags;
 };
 
+/**
+ * The <code>PPB_HostResolver_Dev</code> interface supports host name
+ * resolution.
+ *
+ * Permissions: In order to run <code>Resolve()</code>, apps permission
+ * <code>socket</code> with subrule <code>resolve-host</code> is required.
+ * For more details about network communication permissions, please see:
+ * http://developer.chrome.com/apps/app_network.html
+ */
 interface PPB_HostResolver_Dev {
   /**
-   * Allocates a Host Resolver resource.
+   * Creates a host resolver resource.
+   *
+   * @param[in] instance A <code>PP_Instance</code> identifying one instance of
+   * a module.
+   *
+   * @return A <code>PP_Resource</code> corresponding to a host reslover or 0
+   * on failure.
    */
   PP_Resource Create([in] PP_Instance instance);
 
   /**
-   * Determines if a given resource is a Host Resolver.
+   * Determines if a given resource is a host resolver.
+   *
+   * @param[in] resource A <code>PP_Resource</code> to check.
+   *
+   * @return <code>PP_TRUE</code> if the input is a
+   * <code>PPB_HostResolver_Dev</code> resource; <code>PP_FALSE</code>
+   * otherwise.
    */
   PP_Bool IsHostResolver([in] PP_Resource resource);
 
   /**
-   * Creates a new request to Host Resolver. |callback| is invoked when request
-   * is processed and a list of network addresses is obtained. These addresses
-   * can be used in Connect, Bind or Listen calls to connect to a given |host|
-   * and |port|.
+   * Requests resolution of a host name. If the call completes successfully, the
+   * results can be retrieved by <code>GetCanonicalName()</code>,
+   * <code>GetNetAddressCount()</code> and <code>GetNetAddress()</code>.
+   *
+   * @param[in] host_resolver A <code>PP_Resource</code> corresponding to a host
+   * resolver.
+   * @param[in] host The host name (or IP address literal) to resolve.
+   * @param[in] port The port number to be set in the resulting network
+   * addresses.
+   * @param[in] hint A <code>PP_HostResolver_Hint_Dev</code> structure providing
+   * hints for host resolution.
+   * @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_NAME_NOT_RESOLVED</code> will be
+   * returned if the host name couldn't be resolved.
    */
   int32_t Resolve([in] PP_Resource host_resolver,
                   [in] str_t host,
@@ -57,21 +101,41 @@ interface PPB_HostResolver_Dev {
                   [in] PP_CompletionCallback callback);
 
   /**
-   * Gets canonical name of host. Returns an undefined var if there is a pending
-   * Resolve call or the previous Resolve call failed.
+   * Gets the canonical name of the host.
+   *
+   * @param[in] host_resolver A <code>PP_Resource</code> corresponding to a host
+   * resolver.
+   *
+   * @return A string <code>PP_Var</code> on success, which is an empty string
+   * if <code>PP_HOSTRESOLVER_FLAGS_CANONNAME</code> is not set in the hint
+   * flags when calling <code>Resolve()</code>; an undefined <code>PP_Var</code>
+   * if there is a pending <code>Resolve()</code> call or the previous
+   * <code>Resolve()</code> call failed.
    */
   PP_Var GetCanonicalName([in] PP_Resource host_resolver);
 
   /**
-   * Gets number of network addresses obtained after Resolve call. Returns 0 if
-   * there is a pending Resolve call or the previous Resolve call failed.
+   * Gets the number of network addresses.
+   *
+   * @param[in] host_resolver A <code>PP_Resource</code> corresponding to a host
+   * resolver.
+   *
+   * @return The number of available network addresses on success; 0 if there is
+   * a pending <code>Resolve()</code> call or the previous
+   * <code>Resolve()</code> call failed.
    */
   uint32_t GetNetAddressCount([in] PP_Resource host_resolver);
 
   /**
-   * Gets the |index|-th network address.
-   * Returns 0 if there is a pending Resolve call or the previous Resolve call
-   * failed, or |index| is not less than the number of available addresses.
+   * Gets a network address.
+   *
+   * @param[in] host_resolver A <code>PP_Resource</code> corresponding to a host
+   * resolver.
+   * @param[in] index An index indicating which address to return.
+   *
+   * @return A <code>PPB_NetAddress_Dev</code> resource on success; 0 if there
+   * is a pending <code>Resolve()</code> call or the previous
+   * <code>Resolve()</code> call failed, or the specified index is out of range.
    */
   PP_Resource GetNetAddress([in] PP_Resource host_resolver,
                             [in] uint32_t index);
diff --git a/ppapi/api/dev/ppb_net_address_dev.idl b/ppapi/api/dev/ppb_net_address_dev.idl
index b3d1d1b..cae7d29 100644
--- a/ppapi/api/dev/ppb_net_address_dev.idl
+++ b/ppapi/api/dev/ppb_net_address_dev.idl
@@ -11,6 +11,9 @@ label Chrome {
   M29 = 0.1
 };
 
+/**
+ * Network address family types.
+ */
 [assert_size(4)]
 enum PP_NetAddress_Family_Dev {
   /**
@@ -65,6 +68,13 @@ interface PPB_NetAddress_Dev {
   /**
    * Creates a <code>PPB_NetAddress_Dev</code> resource with the specified IPv4
    * address.
+   *
+   * @param[in] instance A <code>PP_Instance</code> identifying one instance of
+   * a module.
+   * @param[in] ipv4_addr An IPv4 address.
+   *
+   * @return A <code>PP_Resource</code> representing the same address as
+   * <code>ipv4_addr</code> or 0 on failure.
    */
   PP_Resource CreateFromIPv4Address([in] PP_Instance instance,
                                     [in] PP_NetAddress_IPv4_Dev ipv4_addr);
@@ -72,17 +82,35 @@ interface PPB_NetAddress_Dev {
   /**
    * Creates a <code>PPB_NetAddress_Dev</code> resource with the specified IPv6
    * address.
+   *
+   * @param[in] instance A <code>PP_Instance</code> identifying one instance of
+   * a module.
+   * @param[in] ipv6_addr An IPv6 address.
+   *
+   * @return A <code>PP_Resource</code> representing the same address as
+   * <code>ipv6_addr</code> or 0 on failure.
    */
   PP_Resource CreateFromIPv6Address([in] PP_Instance instance,
                                     [in] PP_NetAddress_IPv6_Dev ipv6_addr);
 
   /**
    * Determines if a given resource is a network address.
+   *
+   * @param[in] resource A <code>PP_Resource</code> to check.
+   *
+   * @return <code>PP_TRUE</code> if the input is a
+   * <code>PPB_NetAddress_Dev</code> resource; <code>PP_FALSE</code> otherwise.
    */
-  PP_Bool IsNetAddress([in] PP_Resource addr);
+  PP_Bool IsNetAddress([in] PP_Resource resource);
 
   /**
    * Gets the address family.
+   *
+   * @param[in] addr A <code>PP_Resource</code> corresponding to a network
+   * address.
+   *
+   * @return The address family on success;
+   * <code>PP_NETADDRESS_FAMILY_UNSPECIFIED</code> on failure.
    */
   PP_NetAddress_Family_Dev GetFamily([in] PP_Resource addr);
 
@@ -91,7 +119,14 @@ interface PPB_NetAddress_Dev {
    * description is in the form of host [ ":" port ] and conforms to
    * http://tools.ietf.org/html/rfc3986#section-3.2 for IPv4 and IPv6 addresses
    * (e.g., "192.168.0.1", "192.168.0.1:99", or "[::1]:80").
-   * Returns an undefined var on failure.
+   *
+   * @param[in] addr A <code>PP_Resource</code> corresponding to a network
+   * address.
+   * @param[in] include_port Whether to include the port number in the
+   * description.
+   *
+   * @return A string <code>PP_Var</code> on success; an undefined
+   * <code>PP_Var</code> on failure.
    */
   PP_Var DescribeAsString([in] PP_Resource addr,
                           [in] PP_Bool include_port);
@@ -99,9 +134,17 @@ interface PPB_NetAddress_Dev {
   /**
    * Fills a <code>PP_NetAddress_IPv4_Dev</code> structure if the network
    * address is of <code>PP_NETADDRESS_FAMILY_IPV4</code> address family.
-   * Returns PP_FALSE on failure. Note that passing a network address of
+   * Note that passing a network address of
    * <code>PP_NETADDRESS_FAMILY_IPV6</code> address family will fail even if the
    * address is an IPv4-mapped IPv6 address.
+   *
+   * @param[in] addr A <code>PP_Resource</code> corresponding to a network
+   * address.
+   * @param[out] ipv4_addr A <code>PP_NetAddress_IPv4_Dev</code> structure to
+   * store the result.
+   *
+   * @return A <code>PP_Bool</code> value indicating whether the operation
+   * succeeded.
    */
   PP_Bool DescribeAsIPv4Address([in] PP_Resource addr,
                                 [out] PP_NetAddress_IPv4_Dev ipv4_addr);
@@ -109,9 +152,17 @@ interface PPB_NetAddress_Dev {
   /**
    * Fills a <code>PP_NetAddress_IPv6_Dev</code> structure if the network
    * address is of <code>PP_NETADDRESS_FAMILY_IPV6</code> address family.
-   * Returns PP_FALSE on failure. Note that passing a network address of
+   * Note that passing a network address of
    * <code>PP_NETADDRESS_FAMILY_IPV4</code> address family will fail - this
    * method doesn't map it to an IPv6 address.
+   *
+   * @param[in] addr A <code>PP_Resource</code> corresponding to a network
+   * address.
+   * @param[out] ipv6_addr A <code>PP_NetAddress_IPv6_Dev</code> structure to
+   * store the result.
+   *
+   * @return A <code>PP_Bool</code> value indicating whether the operation
+   * succeeded.
    */
   PP_Bool DescribeAsIPv6Address([in] PP_Resource addr,
                                 [out] PP_NetAddress_IPv6_Dev ipv6_addr);
diff --git a/ppapi/api/dev/ppb_tcp_socket_dev.idl b/ppapi/api/dev/ppb_tcp_socket_dev.idl
index 920a9e9..c0b8d0d 100644
--- a/ppapi/api/dev/ppb_tcp_socket_dev.idl
+++ b/ppapi/api/dev/ppb_tcp_socket_dev.idl
@@ -13,71 +13,134 @@ label Chrome {
   M29 = 0.1
 };
 
+/**
+ * Option names used by <code>SetOption()</code>.
+ */
 [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.
-  // This option can only be set after a successful Connect() call.
+  /**
+   * Disables coalescing of small writes to make TCP segments, and instead
+   * delivers data immediately. Value's type is <code>PP_VARTYPE_BOOL</code>.
+   * 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.
-  // This option can only be set after a successful Connect() call.
-  // 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 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>Connect()</code> call.
+   *
+   * Note: This is only treated as a hint for the browser to set the buffer
+   * size. Even if <code>SetOption()</code> succeeds, the browser doesn't
+   * guarantee it will conform to the size.
+   */
   PP_TCPSOCKET_OPTION_SEND_BUFFER_SIZE = 1,
 
-  // Specifies the socket receive buffer in bytes. Value's type should be
-  // PP_VARTYPE_INT32.
-  // This option can only be set after a successful Connect() call.
-  // 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 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>Connect()</code> call.
+   *
+   * Note: This is only treated as a hint for the browser to set the buffer
+   * size. Even if <code>SetOption()</code> succeeds, the browser doesn't
+   * guarantee it will conform to the size.
+   */
   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 the socket 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,
                   [in] PP_CompletionCallback callback);
 
   /**
-   * Gets the local address of the socket, if it has been connected.
-   * Returns a PPB_NetAddress_Dev resource on success; returns 0 on failure.
+   * Gets the local address of the socket, if it is connected.
+   *
+   * @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.
+   * Gets the remote address of the socket, if it is connected.
+   *
+   * @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. The socket must be connected. 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,
@@ -85,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. The socket must be connected. 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,
@@ -96,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 and disconnects 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, no output
+   * buffer pointers passed into previous <code>Read()</code> calls will 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.
+   * 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 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,
diff --git a/ppapi/api/dev/ppb_udp_socket_dev.idl b/ppapi/api/dev/ppb_udp_socket_dev.idl
index a4d7d53..95d02ac 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,65 +13,125 @@ label Chrome {
   M29 = 0.1
 };
 
+/**
+ * Option names 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.
-  // This option can only be set before calling Bind().
+  /**
+   * 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.
-  // This option can only be set before calling Bind().
+  /**
+   * 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.
-  // This option can only be set after a successful Bind() call.
-  // 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> succeeds, the browser doesn't
+   * guarantee it will conform to the size.
+   */
   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.
-  // This option can only be set after a successful Bind() call.
-  // 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> succeeds, the browser doesn't
+   * guarantee it will conform to the size.
+   */
   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 the socket to the given address.
+   *
+   * @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.
+   * Gets the address that the socket is bound to. The socket must be bound.
+   *
+   * @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. The socket
+   * must be bound.
+   *
+   * @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 receive.
+   * @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,
@@ -81,9 +140,21 @@ 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. The socket must be bound.
+   *
+   * @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
+   * destination 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,
@@ -92,17 +163,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, no output
+   * parameters passed into previous <code>RecvFrom()</code> calls will 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 on |udp_socket|.
-   * 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 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,
diff --git a/ppapi/c/dev/ppb_host_resolver_dev.h b/ppapi/c/dev/ppb_host_resolver_dev.h
index 95a992d..ea12eda 100644
--- a/ppapi/c/dev/ppb_host_resolver_dev.h
+++ b/ppapi/c/dev/ppb_host_resolver_dev.h
@@ -3,7 +3,7 @@
  * found in the LICENSE file.
  */
 
-/* From dev/ppb_host_resolver_dev.idl modified Wed Jun 19 11:37:25 2013. */
+/* From dev/ppb_host_resolver_dev.idl modified Thu Jun 20 12:08:29 2013. */
 
 #ifndef PPAPI_C_DEV_PPB_HOST_RESOLVER_DEV_H_
 #define PPAPI_C_DEV_PPB_HOST_RESOLVER_DEV_H_
@@ -23,7 +23,6 @@
 /**
  * @file
  * This file defines the <code>PPB_HostResolver_Dev</code> interface.
- * TODO(yzshen): Tidy up the document.
  */
 
 
@@ -32,13 +31,14 @@
  * @{
  */
 /**
- * The <code>PP_HostResolver_Flags_Dev</code> is an enumeration of the
- * different types of flags, that can be OR-ed and passed to host
- * resolver. Currently there is only one flag defined.
+ * <code>PP_HostResolver_Flags_Dev</code> is an enumeration of flags which can
+ * be OR-ed and passed to the host resolver. Currently there is only one flag
+ * defined.
  */
 typedef enum {
   /**
-   * AI_CANONNAME
+   * Hint to request the canonical name of the host, which can be retrieved by
+   * <code>GetCanonicalName()</code>.
    */
   PP_HOSTRESOLVER_FLAGS_CANONNAME = 1 << 0
 } PP_HostResolver_Flags_Dev;
@@ -51,8 +51,17 @@ PP_COMPILE_ASSERT_SIZE_IN_BYTES(PP_HostResolver_Flags_Dev, 4);
  * @addtogroup Structs
  * @{
  */
+/**
+ * <code>PP_HostResolver_Hint_Dev</code> represents hints for host resolution.
+ */
 struct PP_HostResolver_Hint_Dev {
+  /**
+   * Network address family.
+   */
   PP_NetAddress_Family_Dev family;
+  /**
+   * Combination of flags from <code>PP_HostResolver_Flags_Dev</code>.
+   */
   int32_t flags;
 };
 PP_COMPILE_ASSERT_STRUCT_SIZE_IN_BYTES(PP_HostResolver_Hint_Dev, 8);
@@ -64,20 +73,55 @@ PP_COMPILE_ASSERT_STRUCT_SIZE_IN_BYTES(PP_HostResolver_Hint_Dev, 8);
  * @addtogroup Interfaces
  * @{
  */
+/**
+ * The <code>PPB_HostResolver_Dev</code> interface supports host name
+ * resolution.
+ *
+ * Permissions: In order to run <code>Resolve()</code>, apps permission
+ * <code>socket</code> with subrule <code>resolve-host</code> is required.
+ * For more details about network communication permissions, please see:
+ * http://developer.chrome.com/apps/app_network.html
+ */
 struct PPB_HostResolver_Dev_0_1 {
   /**
-   * Allocates a Host Resolver resource.
+   * Creates a host resolver resource.
+   *
+   * @param[in] instance A <code>PP_Instance</code> identifying one instance of
+   * a module.
+   *
+   * @return A <code>PP_Resource</code> corresponding to a host reslover or 0
+   * on failure.
    */
   PP_Resource (*Create)(PP_Instance instance);
   /**
-   * Determines if a given resource is a Host Resolver.
+   * Determines if a given resource is a host resolver.
+   *
+   * @param[in] resource A <code>PP_Resource</code> to check.
+   *
+   * @return <code>PP_TRUE</code> if the input is a
+   * <code>PPB_HostResolver_Dev</code> resource; <code>PP_FALSE</code>
+   * otherwise.
    */
   PP_Bool (*IsHostResolver)(PP_Resource resource);
   /**
-   * Creates a new request to Host Resolver. |callback| is invoked when request
-   * is processed and a list of network addresses is obtained. These addresses
-   * can be used in Connect, Bind or Listen calls to connect to a given |host|
-   * and |port|.
+   * Requests resolution of a host name. If the call completes successfully, the
+   * results can be retrieved by <code>GetCanonicalName()</code>,
+   * <code>GetNetAddressCount()</code> and <code>GetNetAddress()</code>.
+   *
+   * @param[in] host_resolver A <code>PP_Resource</code> corresponding to a host
+   * resolver.
+   * @param[in] host The host name (or IP address literal) to resolve.
+   * @param[in] port The port number to be set in the resulting network
+   * addresses.
+   * @param[in] hint A <code>PP_HostResolver_Hint_Dev</code> structure providing
+   * hints for host resolution.
+   * @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_NAME_NOT_RESOLVED</code> will be
+   * returned if the host name couldn't be resolved.
    */
   int32_t (*Resolve)(PP_Resource host_resolver,
                      const char* host,
@@ -85,19 +129,39 @@ struct PPB_HostResolver_Dev_0_1 {
                      const struct PP_HostResolver_Hint_Dev* hint,
                      struct PP_CompletionCallback callback);
   /**
-   * Gets canonical name of host. Returns an undefined var if there is a pending
-   * Resolve call or the previous Resolve call failed.
+   * Gets the canonical name of the host.
+   *
+   * @param[in] host_resolver A <code>PP_Resource</code> corresponding to a host
+   * resolver.
+   *
+   * @return A string <code>PP_Var</code> on success, which is an empty string
+   * if <code>PP_HOSTRESOLVER_FLAGS_CANONNAME</code> is not set in the hint
+   * flags when calling <code>Resolve()</code>; an undefined <code>PP_Var</code>
+   * if there is a pending <code>Resolve()</code> call or the previous
+   * <code>Resolve()</code> call failed.
    */
   struct PP_Var (*GetCanonicalName)(PP_Resource host_resolver);
   /**
-   * Gets number of network addresses obtained after Resolve call. Returns 0 if
-   * there is a pending Resolve call or the previous Resolve call failed.
+   * Gets the number of network addresses.
+   *
+   * @param[in] host_resolver A <code>PP_Resource</code> corresponding to a host
+   * resolver.
+   *
+   * @return The number of available network addresses on success; 0 if there is
+   * a pending <code>Resolve()</code> call or the previous
+   * <code>Resolve()</code> call failed.
    */
   uint32_t (*GetNetAddressCount)(PP_Resource host_resolver);
   /**
-   * Gets the |index|-th network address.
-   * Returns 0 if there is a pending Resolve call or the previous Resolve call
-   * failed, or |index| is not less than the number of available addresses.
+   * Gets a network address.
+   *
+   * @param[in] host_resolver A <code>PP_Resource</code> corresponding to a host
+   * resolver.
+   * @param[in] index An index indicating which address to return.
+   *
+   * @return A <code>PPB_NetAddress_Dev</code> resource on success; 0 if there
+   * is a pending <code>Resolve()</code> call or the previous
+   * <code>Resolve()</code> call failed, or the specified index is out of range.
    */
   PP_Resource (*GetNetAddress)(PP_Resource host_resolver, uint32_t index);
 };
diff --git a/ppapi/c/dev/ppb_net_address_dev.h b/ppapi/c/dev/ppb_net_address_dev.h
index 3ce3f52..445679e 100644
--- a/ppapi/c/dev/ppb_net_address_dev.h
+++ b/ppapi/c/dev/ppb_net_address_dev.h
@@ -3,7 +3,7 @@
  * found in the LICENSE file.
  */
 
-/* From dev/ppb_net_address_dev.idl modified Mon Jun 10 17:42:43 2013. */
+/* From dev/ppb_net_address_dev.idl modified Thu Jun 20 12:10:09 2013. */
 
 #ifndef PPAPI_C_DEV_PPB_NET_ADDRESS_DEV_H_
 #define PPAPI_C_DEV_PPB_NET_ADDRESS_DEV_H_
@@ -28,6 +28,9 @@
  * @addtogroup Enums
  * @{
  */
+/**
+ * Network address family types.
+ */
 typedef enum {
   /**
    * The address family is unspecified.
@@ -96,6 +99,13 @@ struct PPB_NetAddress_Dev_0_1 {
   /**
    * Creates a <code>PPB_NetAddress_Dev</code> resource with the specified IPv4
    * address.
+   *
+   * @param[in] instance A <code>PP_Instance</code> identifying one instance of
+   * a module.
+   * @param[in] ipv4_addr An IPv4 address.
+   *
+   * @return A <code>PP_Resource</code> representing the same address as
+   * <code>ipv4_addr</code> or 0 on failure.
    */
   PP_Resource (*CreateFromIPv4Address)(
       PP_Instance instance,
@@ -103,16 +113,34 @@ struct PPB_NetAddress_Dev_0_1 {
   /**
    * Creates a <code>PPB_NetAddress_Dev</code> resource with the specified IPv6
    * address.
+   *
+   * @param[in] instance A <code>PP_Instance</code> identifying one instance of
+   * a module.
+   * @param[in] ipv6_addr An IPv6 address.
+   *
+   * @return A <code>PP_Resource</code> representing the same address as
+   * <code>ipv6_addr</code> or 0 on failure.
    */
   PP_Resource (*CreateFromIPv6Address)(
       PP_Instance instance,
       const struct PP_NetAddress_IPv6_Dev* ipv6_addr);
   /**
    * Determines if a given resource is a network address.
+   *
+   * @param[in] resource A <code>PP_Resource</code> to check.
+   *
+   * @return <code>PP_TRUE</code> if the input is a
+   * <code>PPB_NetAddress_Dev</code> resource; <code>PP_FALSE</code> otherwise.
    */
-  PP_Bool (*IsNetAddress)(PP_Resource addr);
+  PP_Bool (*IsNetAddress)(PP_Resource resource);
   /**
    * Gets the address family.
+   *
+   * @param[in] addr A <code>PP_Resource</code> corresponding to a network
+   * address.
+   *
+   * @return The address family on success;
+   * <code>PP_NETADDRESS_FAMILY_UNSPECIFIED</code> on failure.
    */
   PP_NetAddress_Family_Dev (*GetFamily)(PP_Resource addr);
   /**
@@ -120,24 +148,47 @@ struct PPB_NetAddress_Dev_0_1 {
    * description is in the form of host [ ":" port ] and conforms to
    * http://tools.ietf.org/html/rfc3986#section-3.2 for IPv4 and IPv6 addresses
    * (e.g., "192.168.0.1", "192.168.0.1:99", or "[::1]:80").
-   * Returns an undefined var on failure.
+   *
+   * @param[in] addr A <code>PP_Resource</code> corresponding to a network
+   * address.
+   * @param[in] include_port Whether to include the port number in the
+   * description.
+   *
+   * @return A string <code>PP_Var</code> on success; an undefined
+   * <code>PP_Var</code> on failure.
    */
   struct PP_Var (*DescribeAsString)(PP_Resource addr, PP_Bool include_port);
   /**
    * Fills a <code>PP_NetAddress_IPv4_Dev</code> structure if the network
    * address is of <code>PP_NETADDRESS_FAMILY_IPV4</code> address family.
-   * Returns PP_FALSE on failure. Note that passing a network address of
+   * Note that passing a network address of
    * <code>PP_NETADDRESS_FAMILY_IPV6</code> address family will fail even if the
    * address is an IPv4-mapped IPv6 address.
+   *
+   * @param[in] addr A <code>PP_Resource</code> corresponding to a network
+   * address.
+   * @param[out] ipv4_addr A <code>PP_NetAddress_IPv4_Dev</code> structure to
+   * store the result.
+   *
+   * @return A <code>PP_Bool</code> value indicating whether the operation
+   * succeeded.
    */
   PP_Bool (*DescribeAsIPv4Address)(PP_Resource addr,
                                    struct PP_NetAddress_IPv4_Dev* ipv4_addr);
   /**
    * Fills a <code>PP_NetAddress_IPv6_Dev</code> structure if the network
    * address is of <code>PP_NETADDRESS_FAMILY_IPV6</code> address family.
-   * Returns PP_FALSE on failure. Note that passing a network address of
+   * Note that passing a network address of
    * <code>PP_NETADDRESS_FAMILY_IPV4</code> address family will fail - this
    * method doesn't map it to an IPv6 address.
+   *
+   * @param[in] addr A <code>PP_Resource</code> corresponding to a network
+   * address.
+   * @param[out] ipv6_addr A <code>PP_NetAddress_IPv6_Dev</code> structure to
+   * store the result.
+   *
+   * @return A <code>PP_Bool</code> value indicating whether the operation
+   * succeeded.
    */
   PP_Bool (*DescribeAsIPv6Address)(PP_Resource addr,
                                    struct PP_NetAddress_IPv6_Dev* ipv6_addr);
diff --git a/ppapi/c/dev/ppb_tcp_socket_dev.h b/ppapi/c/dev/ppb_tcp_socket_dev.h
index 044a03e..b5016c6 100644
--- a/ppapi/c/dev/ppb_tcp_socket_dev.h
+++ b/ppapi/c/dev/ppb_tcp_socket_dev.h
@@ -3,7 +3,7 @@
  * found in the LICENSE file.
  */
 
-/* From dev/ppb_tcp_socket_dev.idl modified Tue Jun 18 15:48:42 2013. */
+/* From dev/ppb_tcp_socket_dev.idl modified Thu Jun 20 15:14:26 2013. */
 
 #ifndef PPAPI_C_DEV_PPB_TCP_SOCKET_DEV_H_
 #define PPAPI_C_DEV_PPB_TCP_SOCKET_DEV_H_
@@ -29,24 +29,35 @@
  * @addtogroup Enums
  * @{
  */
+/**
+ * Option names used by <code>SetOption()</code>.
+ */
 typedef enum {
-  /* Disables coalescing of small writes to make TCP segments, and instead
-   * deliver data immediately. Value type is PP_VARTYPE_BOOL.
-   * This option can only be set after a successful Connect() call. */
+  /**
+   * Disables coalescing of small writes to make TCP segments, and instead
+   * delivers data immediately. Value's type is <code>PP_VARTYPE_BOOL</code>.
+   * 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.
-   * This option can only be set after a successful Connect() call.
+  /**
+   * 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>Connect()</code> call.
+   *
    * 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. */
+   * size. Even if <code>SetOption()</code> succeeds, the browser doesn't
+   * guarantee it will conform to the size.
+   */
   PP_TCPSOCKET_OPTION_SEND_BUFFER_SIZE = 1,
-  /* Specifies the socket receive buffer in bytes. Value's type should be
-   * PP_VARTYPE_INT32.
-   * This option can only be set after a successful Connect() call.
+  /**
+   * 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>Connect()</code> call.
+   *
    * 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. */
+   * size. Even if <code>SetOption()</code> succeeds, the browser doesn't
+   * guarantee it will conform to the size.
+   */
   PP_TCPSOCKET_OPTION_RECV_BUFFER_SIZE = 2
 } PP_TCPSocket_Option_Dev;
 PP_COMPILE_ASSERT_SIZE_IN_BYTES(PP_TCPSocket_Option_Dev, 4);
@@ -60,69 +71,142 @@ PP_COMPILE_ASSERT_SIZE_IN_BYTES(PP_TCPSocket_Option_Dev, 4);
  */
 /**
  * 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
  */
 struct PPB_TCPSocket_Dev_0_1 {
   /**
-   * 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)(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)(PP_Resource resource);
   /**
-   * Connects to an address given by |addr|, which is a PPB_NetAddress_Dev
-   * resource.
+   * Connects the socket 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)(PP_Resource tcp_socket,
                      PP_Resource addr,
                      struct PP_CompletionCallback callback);
   /**
-   * Gets the local address of the socket, if it has been connected.
-   * Returns a PPB_NetAddress_Dev resource on success; returns 0 on failure.
+   * Gets the local address of the socket, if it is connected.
+   *
+   * @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)(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.
+   * Gets the remote address of the socket, if it is connected.
+   *
+   * @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)(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. The socket must be connected. 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)(PP_Resource tcp_socket,
                   char* buffer,
                   int32_t bytes_to_read,
                   struct 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. The socket must be connected. 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)(PP_Resource tcp_socket,
                    const char* buffer,
                    int32_t bytes_to_write,
                    struct 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 and disconnects 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, no output
+   * buffer pointers passed into previous <code>Read()</code> calls will 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)(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.
+   * 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 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)(PP_Resource tcp_socket,
                        PP_TCPSocket_Option_Dev name,
diff --git a/ppapi/c/dev/ppb_udp_socket_dev.h b/ppapi/c/dev/ppb_udp_socket_dev.h
index 95511c0..89436ad 100644
--- a/ppapi/c/dev/ppb_udp_socket_dev.h
+++ b/ppapi/c/dev/ppb_udp_socket_dev.h
@@ -3,7 +3,7 @@
  * found in the LICENSE file.
  */
 
-/* From dev/ppb_udp_socket_dev.idl modified Tue Jun 18 22:26:29 2013. */
+/* From dev/ppb_udp_socket_dev.idl modified Thu Jun 20 15:15:36 2013. */
 
 #ifndef PPAPI_C_DEV_PPB_UDP_SOCKET_DEV_H_
 #define PPAPI_C_DEV_PPB_UDP_SOCKET_DEV_H_
@@ -22,7 +22,6 @@
 /**
  * @file
  * This file defines the <code>PPB_UDPSocket_Dev</code> interface.
- * TODO(yzshen): Tidy up the document.
  */
 
 
@@ -30,28 +29,41 @@
  * @addtogroup Enums
  * @{
  */
+/**
+ * Option names used by <code>SetOption()</code>.
+ */
 typedef enum {
-  /* 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.
-   * This option can only be set before calling Bind(). */
+  /**
+   * 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.
-   * This option can only be set before calling Bind(). */
+  /**
+   * 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.
-   * This option can only be set after a successful Bind() call.
+  /**
+   * 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 SetOption() reports that this option has been successfully
-   * set, the browser doesn't guarantee it will conform to it. */
+   * size. Even if <code>SetOption()</code> succeeds, the browser doesn't
+   * guarantee it will conform to the size.
+   */
   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.
-   * This option can only be set after a successful Bind() call.
+  /**
+   * 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 SetOption() reports that this option has been successfully
-   * set, the browser doesn't guarantee it will conform to it. */
+   * size. Even if <code>SetOption()</code> succeeds, the browser doesn't
+   * guarantee it will conform to the size.
+   */
   PP_UDPSOCKET_OPTION_RECV_BUFFER_SIZE = 3
 } PP_UDPSocket_Option_Dev;
 PP_COMPILE_ASSERT_SIZE_IN_BYTES(PP_UDPSocket_Option_Dev, 4);
@@ -63,32 +75,79 @@ PP_COMPILE_ASSERT_SIZE_IN_BYTES(PP_UDPSocket_Option_Dev, 4);
  * @addtogroup Interfaces
  * @{
  */
+/**
+ * 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
+ */
 struct PPB_UDPSocket_Dev_0_1 {
   /**
    * 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)(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)(PP_Resource resource);
   /**
-   * Binds to the address given by |addr|, which is a PPB_NetAddress_Dev
-   * resource.
+   * Binds the socket to the given address.
+   *
+   * @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)(PP_Resource udp_socket,
                   PP_Resource addr,
                   struct 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.
+   * Gets the address that the socket is bound to. The socket must be bound.
+   *
+   * @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)(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. The socket
+   * must be bound.
+   *
+   * @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 receive.
+   * @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)(PP_Resource udp_socket,
                       char* buffer,
@@ -96,9 +155,21 @@ struct PPB_UDPSocket_Dev_0_1 {
                       PP_Resource* addr,
                       struct 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. The socket must be bound.
+   *
+   * @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
+   * destination 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)(PP_Resource udp_socket,
                     const char* buffer,
@@ -106,16 +177,32 @@ struct PPB_UDPSocket_Dev_0_1 {
                     PP_Resource addr,
                     struct 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, no output
+   * parameters passed into previous <code>RecvFrom()</code> calls will 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)(PP_Resource udp_socket);
   /**
-   * Sets a socket option on |udp_socket|.
-   * 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 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)(PP_Resource udp_socket,
                        PP_UDPSocket_Option_Dev name,
diff --git a/ppapi/cpp/dev/host_resolver_dev.h b/ppapi/cpp/dev/host_resolver_dev.h
index 592fd74..a746306 100644
--- a/ppapi/cpp/dev/host_resolver_dev.h
+++ b/ppapi/cpp/dev/host_resolver_dev.h
@@ -17,29 +17,96 @@ namespace pp {
 class CompletionCallback;
 class InstanceHandle;
 
+/// The <code>HostResolver_Dev</code> class supports host name resolution.
+///
+/// Permissions: In order to run <code>Resolve()</code>, apps permission
+/// <code>socket</code> with subrule <code>resolve-host</code> is required.
+/// For more details about network communication permissions, please see:
+/// http://developer.chrome.com/apps/app_network.html
 class HostResolver_Dev : public Resource {
  public:
+  /// Default constructor for creating an is_null()
+  /// <code>HostResolver_Dev</code> object.
   HostResolver_Dev();
 
+  /// A constructor used to create a <code>HostResolver_Dev</code> object.
+  ///
+  /// @param[in] instance The instance with which this resource will be
+  /// associated.
   explicit HostResolver_Dev(const InstanceHandle& instance);
 
+  /// A constructor used when you have received a <code>PP_Resource</code> as a
+  /// return value that has had 1 ref added for you.
+  ///
+  /// @param[in] resource A <code>PPB_HostResolver_Dev</code> resource.
   HostResolver_Dev(PassRef, PP_Resource resource);
 
+  /// The copy constructor for <code>HostResolver_Dev</code>.
+  ///
+  /// @param[in] other A reference to another <code>HostResolver_Dev</code>.
   HostResolver_Dev(const HostResolver_Dev& other);
 
+  /// The destructor.
   virtual ~HostResolver_Dev();
 
+  /// The assignment operator for <code>HostResolver_Dev</code>.
+  ///
+  /// @param[in] other A reference to another <code>HostResolver_Dev</code>.
+  ///
+  /// @return A reference to this <code>HostResolver_Dev</code> object.
   HostResolver_Dev& operator=(const HostResolver_Dev& other);
 
-  // Returns true if the required interface is available.
+  /// Static function for determining whether the browser supports the
+  /// <code>PPB_HostResolver_Dev</code> interface.
+  ///
+  /// @return true if the interface is available, false otherwise.
   static bool IsAvailable();
 
+  /// Requests resolution of a host name. If the call completes successully, the
+  /// results can be retrieved by <code>GetCanonicalName()</code>,
+  /// <code>GetNetAddressCount()</code> and <code>GetNetAddress()</code>.
+  ///
+  /// @param[in] host The host name (or IP address literal) to resolve.
+  /// @param[in] port The port number to be set in the resulting network
+  /// addresses.
+  /// @param[in] hint A <code>PP_HostResolver_Hint_Dev</code> structure
+  /// providing hints for host resolution.
+  /// @param[in] callback A <code>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_NAME_NOT_RESOLVED</code> will be
+  /// returned if the host name couldn't be resolved.
   int32_t Resolve(const char* host,
                   uint16_t port,
                   const PP_HostResolver_Hint_Dev& hint,
                   const CompletionCallback& callback);
+
+  /// Gets the canonical name of the host.
+  ///
+  /// @return A string <code>Var</code> on success, which is an empty string
+  /// if <code>PP_HOSTRESOLVER_FLAGS_CANONNAME</code> is not set in the hint
+  /// flags when calling <code>Resolve()</code>; an undefined <code>Var</code>
+  /// if there is a pending <code>Resolve()</code> call or the previous
+  /// <code>Resolve()</code> call failed.
   Var GetCanonicalName() const;
+
+  /// Gets the number of network addresses.
+  ///
+  /// @return The number of available network addresses on success; 0 if there
+  /// is a pending <code>Resolve()</code> call or the previous
+  /// <code>Resolve()</code> call failed.
   uint32_t GetNetAddressCount() const;
+
+  /// Gets a network address.
+  ///
+  /// @param[in] index An index indicating which address to return.
+  ///
+  /// @return A <code>NetAddress_Dev</code> object. The object will be null
+  /// (i.e., is_null() returns true) if there is a pending
+  /// <code>Resolve()</code> call or the previous <code>Resolve()</code> call
+  /// failed, or the specified index is out of range.
   NetAddress_Dev GetNetAddress(uint32_t index) const;
 };
 
diff --git a/ppapi/cpp/dev/net_address_dev.h b/ppapi/cpp/dev/net_address_dev.h
index e703980..4090aa3 100644
--- a/ppapi/cpp/dev/net_address_dev.h
+++ b/ppapi/cpp/dev/net_address_dev.h
@@ -14,36 +14,98 @@ namespace pp {
 
 class InstanceHandle;
 
+/// The <code>NetAddress_Dev</code> class represents a network address.
 class NetAddress_Dev : public Resource {
  public:
+  /// Default constructor for creating an is_null() <code>NetAddress_Dev</code>
+  /// object.
   NetAddress_Dev();
 
+  /// A constructor used when you have received a <code>PP_Resource</code> as a
+  /// return value that has had 1 ref added for you.
+  ///
+  /// @param[in] resource A <code>PPB_NetAddress_Dev</code> resource.
   NetAddress_Dev(PassRef, PP_Resource resource);
 
+  /// A constructor used to create a <code>NetAddress_Dev</code> object with the
+  /// specified IPv4 address.
+  ///
+  /// @param[in] instance The instance with which this resource will be
+  /// associated.
+  /// @param[in] ipv4_addr An IPv4 address.
   NetAddress_Dev(const InstanceHandle& instance,
                  const PP_NetAddress_IPv4_Dev& ipv4_addr);
 
+  /// A constructor used to create a <code>NetAddress_Dev</code> object with the
+  /// specified IPv6 address.
+  ///
+  /// @param[in] instance The instance with which this resource will be
+  /// associated.
+  /// @param[in] ipv6_addr An IPv6 address.
   NetAddress_Dev(const InstanceHandle& instance,
                  const PP_NetAddress_IPv6_Dev& ipv6_addr);
 
+  /// The copy constructor for <code>NetAddress_Dev</code>.
+  ///
+  /// @param[in] other A reference to another <code>NetAddress_Dev</code>.
   NetAddress_Dev(const NetAddress_Dev& other);
 
+  /// The destructor.
   virtual ~NetAddress_Dev();
 
+  /// The assignment operator for <code>NetAddress_Dev</code>.
+  ///
+  /// @param[in] other A reference to another <code>NetAddress_Dev</code>.
+  ///
+  /// @return A reference to this <code>NetAddress_Dev</code> object.
   NetAddress_Dev& operator=(const NetAddress_Dev& other);
 
-  /// Static function for determining whether the browser supports the required
-  /// NetAddress interface.
+  /// Static function for determining whether the browser supports the
+  /// <code>PPB_NetAddress_Dev</code> interface.
   ///
   /// @return true if the interface is available, false otherwise.
   static bool IsAvailable();
 
+  /// Gets the address family.
+  ///
+  /// @return The address family on success;
+  /// <code>PP_NETADDRESS_FAMILY_UNSPECIFIED</code> on failure.
   PP_NetAddress_Family_Dev GetFamily() const;
 
+  /// Returns a human-readable description of the network address. The
+  /// description is in the form of host [ ":" port ] and conforms to
+  /// http://tools.ietf.org/html/rfc3986#section-3.2 for IPv4 and IPv6 addresses
+  /// (e.g., "192.168.0.1", "192.168.0.1:99", or "[::1]:80").
+  ///
+  /// @param[in] include_port Whether to include the port number in the
+  /// description.
+  ///
+  /// @return A string <code>Var</code> on success; an undefined
+  /// <code>Var</code> on failure.
   Var DescribeAsString(bool include_port) const;
 
+  /// Fills a <code>PP_NetAddress_IPv4_Dev</code> structure if the network
+  /// address is of <code>PP_NETADDRESS_FAMILY_IPV4</code> address family.
+  /// Note that passing a network address of
+  /// <code>PP_NETADDRESS_FAMILY_IPV6</code> address family will fail even if
+  /// the address is an IPv4-mapped IPv6 address.
+  ///
+  /// @param[out] ipv4_addr A <code>PP_NetAddress_IPv4_Dev</code> structure to
+  /// store the result.
+  ///
+  /// @return A boolean value indicating whether the operation succeeded.
   bool DescribeAsIPv4Address(PP_NetAddress_IPv4_Dev* ipv4_addr) const;
 
+  /// Fills a <code>PP_NetAddress_IPv6_Dev</code> structure if the network
+  /// address is of <code>PP_NETADDRESS_FAMILY_IPV6</code> address family.
+  /// Note that passing a network address of
+  /// <code>PP_NETADDRESS_FAMILY_IPV4</code> address family will fail - this
+  /// method doesn't map it to an IPv6 address.
+  ///
+  /// @param[out] ipv6_addr A <code>PP_NetAddress_IPv6_Dev</code> structure to
+  /// store the result.
+  ///
+  /// @return A boolean value indicating whether the operation succeeded.
   bool DescribeAsIPv6Address(PP_NetAddress_IPv6_Dev* ipv6_addr) const;
 };
 
diff --git a/ppapi/cpp/dev/tcp_socket_dev.h b/ppapi/cpp/dev/tcp_socket_dev.h
index 16d7dee..0fc1cd2 100644
--- a/ppapi/cpp/dev/tcp_socket_dev.h
+++ b/ppapi/cpp/dev/tcp_socket_dev.h
@@ -15,34 +15,147 @@ namespace pp {
 class CompletionCallback;
 class InstanceHandle;
 
+/// The <code>TCPSocket_Dev</code> class 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
 class TCPSocket_Dev: public Resource {
  public:
+  /// Default constructor for creating an is_null() <code>TCPSocket_Dev</code>
+  /// object.
   TCPSocket_Dev();
 
+  /// A constructor used to create a <code>TCPSocket_Dev</code> object.
+  ///
+  /// @param[in] instance The instance with which this resource will be
+  /// associated.
   explicit TCPSocket_Dev(const InstanceHandle& instance);
 
+  /// A constructor used when you have received a <code>PP_Resource</code> as a
+  /// return value that has had 1 ref added for you.
+  ///
+  /// @param[in] resource A <code>PPB_TCPSocket_Dev</code> resource.
   TCPSocket_Dev(PassRef, PP_Resource resource);
 
+  /// The copy constructor for <code>TCPSocket_Dev</code>.
+  ///
+  /// @param[in] other A reference to another <code>TCPSocket_Dev</code>.
   TCPSocket_Dev(const TCPSocket_Dev& other);
 
+  /// The destructor.
   virtual ~TCPSocket_Dev();
 
+  /// The assignment operator for <code>TCPSocket_Dev</code>.
+  ///
+  /// @param[in] other A reference to another <code>TCPSocket_Dev</code>.
+  ///
+  /// @return A reference to this <code>TCPSocket_Dev</code> object.
   TCPSocket_Dev& operator=(const TCPSocket_Dev& other);
 
-  // Returns true if the required interface is available.
+  /// Static function for determining whether the browser supports the
+  /// <code>PPB_TCPSocket_Dev</code> interface.
+  ///
+  /// @return true if the interface is available, false otherwise.
   static bool IsAvailable();
 
+  /// Connects the socket to the given address.
+  ///
+  /// @param[in] addr A <code>NetAddress_Dev</code> object.
+  /// @param[in] callback A <code>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(const NetAddress_Dev& addr,
                   const CompletionCallback& callback);
+
+  /// Gets the local address of the socket, if it is connected.
+  ///
+  /// @return A <code>NetAddress_Dev</code> object. The object will be null
+  /// (i.e., is_null() returns true) on failure.
   NetAddress_Dev GetLocalAddress() const;
+
+  /// Gets the remote address of the socket, if it is connected.
+  ///
+  /// @return A <code>NetAddress_Dev</code> object. The object will be null
+  /// (i.e., is_null() returns true) on failure.
   NetAddress_Dev GetRemoteAddress() const;
+
+  /// Reads data from the socket. The socket must be connected. It may perform a
+  /// partial read.
+  ///
+  /// <strong>Caveat:</strong> You should be careful about the lifetime of
+  /// <code>buffer</code>. Typically you will use a
+  /// <code>CompletionCallbackFactory</code> to scope callbacks to the lifetime
+  /// of your class. When your class goes out of scope, the callback factory
+  /// will not actually cancel the operation, but will rather just skip issuing
+  /// the callback on your class. This means that if the underlying
+  /// <code>PPB_TCPSocket_Dev</code> resource outlives your class, the browser
+  /// will still try to write into your buffer when the operation completes.
+  /// The buffer must be kept valid until then to avoid memory corruption.
+  /// If you want to release the buffer while the <code>Read()</code> call is
+  /// still pending, you should call <code>Close()</code> to ensure that the
+  /// buffer won't be accessed in the future.
+  ///
+  /// @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>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(char* buffer,
                int32_t bytes_to_read,
                const CompletionCallback& callback);
+
+  /// Writes data to the socket. The socket must be connected. It may perform a
+  /// partial write.
+  ///
+  /// @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>CompletionCallback</code> to be called upon
+  /// completion.
+  ///
+  /// @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(const char* buffer,
                 int32_t bytes_to_write,
                 const CompletionCallback& callback);
+
+  /// Cancels all pending reads and writes and disconnects 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, no output
+  /// buffer pointers passed into previous <code>Read()</code> calls will 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.
   void Close();
+
+  /// 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] name The option to set.
+  /// @param[in] value The option value to set.
+  /// @param[in] callback A <code>CompletionCallback</code> to be called upon
+  /// completion.
+  ///
+  /// @return An int32_t containing an error code from <code>pp_errors.h</code>.
+  ////
   int32_t SetOption(PP_TCPSocket_Option_Dev name,
                     const Var& value,
                     const CompletionCallback& callback);
diff --git a/ppapi/cpp/dev/udp_socket_dev.h b/ppapi/cpp/dev/udp_socket_dev.h
index 9f46f0a..85f5cb2 100644
--- a/ppapi/cpp/dev/udp_socket_dev.h
+++ b/ppapi/cpp/dev/udp_socket_dev.h
@@ -18,35 +18,138 @@ class Var;
 
 template <typename T> class CompletionCallbackWithOutput;
 
+/// The <code>UDPSocket_Dev</code> class 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
 class UDPSocket_Dev: public Resource {
  public:
+  /// Default constructor for creating an is_null() <code>UDPSocket_Dev</code>
+  /// object.
   UDPSocket_Dev();
 
+  /// A constructor used to create a <code>UDPSocket_Dev</code> object.
+  ///
+  /// @param[in] instance The instance with which this resource will be
+  /// associated.
   explicit UDPSocket_Dev(const InstanceHandle& instance);
 
+  /// A constructor used when you have received a <code>PP_Resource</code> as a
+  /// return value that has had 1 ref added for you.
+  ///
+  /// @param[in] resource A <code>PPB_UDPSocket_Dev</code> resource.
   UDPSocket_Dev(PassRef, PP_Resource resource);
 
+  /// The copy constructor for <code>UDPSocket_Dev</code>.
+  ///
+  /// @param[in] other A reference to another <code>UDPSocket_Dev</code>.
   UDPSocket_Dev(const UDPSocket_Dev& other);
 
+  /// The destructor.
   virtual ~UDPSocket_Dev();
 
+  /// The assignment operator for <code>UDPSocket_Dev</code>.
+  ///
+  /// @param[in] other A reference to another <code>UDPSocket_Dev</code>.
+  ///
+  /// @return A reference to this <code>UDPSocket_Dev</code> object.
   UDPSocket_Dev& operator=(const UDPSocket_Dev& other);
 
-  // Returns true if the required interface is available.
+  /// Static function for determining whether the browser supports the
+  /// <code>PPB_UDPSocket_Dev</code> interface.
+  ///
+  /// @return true if the interface is available, false otherwise.
   static bool IsAvailable();
 
+  /// Binds the socket to the given address.
+  ///
+  /// @param[in] addr A <code>NetAddress_Dev</code> object.
+  /// @param[in] callback A <code>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(const NetAddress_Dev& addr,
                const CompletionCallback& callback);
+
+  /// Get the address that the socket is bound to. The socket must be bound.
+  ///
+  /// @return A <code>NetAddress_Dev</code> object. The object will be null
+  /// (i.e., is_null() returns true) on failure.
   NetAddress_Dev GetBoundAddress();
+
+  /// Receives data from the socket and stores the source address. The socket
+  /// must be bound.
+  ///
+  /// <strong>Caveat:</strong> You should be careful about the lifetime of
+  /// <code>buffer</code>. Typically you will use a
+  /// <code>CompletionCallbackFactory</code> to scope callbacks to the lifetime
+  /// of your class. When your class goes out of scope, the callback factory
+  /// will not actually cancel the operation, but will rather just skip issuing
+  /// the callback on your class. This means that if the underlying
+  /// <code>PPB_UDPSocket_Dev</code> resource outlives your class, the browser
+  /// will still try to write into your buffer when the operation completes.
+  /// The buffer must be kept valid until then to avoid memory corruption.
+  /// If you want to release the buffer while the <code>RecvFrom()</code> call
+  /// is still pending, you should call <code>Close()</code> to ensure that the
+  /// buffer won't be accessed in the future.
+  ///
+  /// @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 receive.
+  /// @param[in] callback A <code>CompletionCallbackWithOutput</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(
       char* buffer,
       int32_t num_bytes,
       const CompletionCallbackWithOutput<NetAddress_Dev>& callback);
+
+  /// Sends data to a specific destination. The socket must be bound.
+  ///
+  /// @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>NetAddress_Dev</code> object holding the
+  /// destination address.
+  /// @param[in] callback A <code>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(const char* buffer,
                  int32_t num_bytes,
                  const NetAddress_Dev& addr,
                  const CompletionCallback& callback);
+
+  /// 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, no output
+  /// paramters passed into previous <code>RecvFrom()</code> calls will 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.
   void Close();
+
+  /// 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] name The option to set.
+  /// @param[in] value The option value to set.
+  /// @param[in] callback A <code>CompletionCallback</code> to be called upon
+  /// completion.
+  ///
+  /// @return An int32_t containing an error code from <code>pp_errors.h</code>.
   int32_t SetOption(PP_UDPSocket_Option_Dev name,
                     const Var& value,
                     const CompletionCallback& callback);
diff --git a/ppapi/native_client/src/untrusted/pnacl_irt_shim/pnacl_shim.c b/ppapi/native_client/src/untrusted/pnacl_irt_shim/pnacl_shim.c
index 9fc6f61..5443916 100644
--- a/ppapi/native_client/src/untrusted/pnacl_irt_shim/pnacl_shim.c
+++ b/ppapi/native_client/src/untrusted/pnacl_irt_shim/pnacl_shim.c
@@ -1573,9 +1573,9 @@ static PP_Resource Pnacl_M29_PPB_NetAddress_Dev_CreateFromIPv6Address(PP_Instanc
   return iface->CreateFromIPv6Address(instance, ipv6_addr);
 }
 
-static PP_Bool Pnacl_M29_PPB_NetAddress_Dev_IsNetAddress(PP_Resource addr) {
+static PP_Bool Pnacl_M29_PPB_NetAddress_Dev_IsNetAddress(PP_Resource resource) {
   const struct PPB_NetAddress_Dev_0_1 *iface = Pnacl_WrapperInfo_PPB_NetAddress_Dev_0_1.real_iface;
-  return iface->IsNetAddress(addr);
+  return iface->IsNetAddress(resource);
 }
 
 static PP_NetAddress_Family_Dev Pnacl_M29_PPB_NetAddress_Dev_GetFamily(PP_Resource addr) {
@@ -4159,7 +4159,7 @@ struct PPB_IMEInputEvent_Dev_0_2 Pnacl_Wrappers_PPB_IMEInputEvent_Dev_0_2 = {
 struct PPB_NetAddress_Dev_0_1 Pnacl_Wrappers_PPB_NetAddress_Dev_0_1 = {
     .CreateFromIPv4Address = (PP_Resource (*)(PP_Instance instance, const struct PP_NetAddress_IPv4_Dev* ipv4_addr))&Pnacl_M29_PPB_NetAddress_Dev_CreateFromIPv4Address,
     .CreateFromIPv6Address = (PP_Resource (*)(PP_Instance instance, const struct PP_NetAddress_IPv6_Dev* ipv6_addr))&Pnacl_M29_PPB_NetAddress_Dev_CreateFromIPv6Address,
-    .IsNetAddress = (PP_Bool (*)(PP_Resource addr))&Pnacl_M29_PPB_NetAddress_Dev_IsNetAddress,
+    .IsNetAddress = (PP_Bool (*)(PP_Resource resource))&Pnacl_M29_PPB_NetAddress_Dev_IsNetAddress,
     .GetFamily = (PP_NetAddress_Family_Dev (*)(PP_Resource addr))&Pnacl_M29_PPB_NetAddress_Dev_GetFamily,
     .DescribeAsString = (struct PP_Var (*)(PP_Resource addr, PP_Bool include_port))&Pnacl_M29_PPB_NetAddress_Dev_DescribeAsString,
     .DescribeAsIPv4Address = (PP_Bool (*)(PP_Resource addr, struct PP_NetAddress_IPv4_Dev* ipv4_addr))&Pnacl_M29_PPB_NetAddress_Dev_DescribeAsIPv4Address,