Update comments of the Pepper networking APIs.

ppapi/api/dev/ppb_net_address_dev.idl

 /* Copyright 2013 The Chromium Authors. All rights reserved.
  * Use of this source code is governed by a BSD-style license that can be
  * found in the LICENSE file.
  */
 
 /**
  * This file defines the <code>PPB_NetAddress_Dev</code> interface.
  */
 
 label Chrome {
   M29 = 0.1
 };
 
+/**
+ * Network address family types.
+ */
 [assert_size(4)]
 enum PP_NetAddress_Family_Dev {
   /**
    * The address family is unspecified.
    */
   PP_NETADDRESS_FAMILY_UNSPECIFIED = 0,
   /**
    * The Internet Protocol version 4 (IPv4) address family.
    */
   PP_NETADDRESS_FAMILY_IPV4 = 1,
@@ skipping 34 matching lines @@
 };
 
 /**
  * The <code>PPB_NetAddress_Dev</code> interface provides operations on
  * network addresses.
  */
 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);
 
   /**
    * 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] addr 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);

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

nit I like to name the parameters to IsFoo functions 'resource' since it might
not be an addr. This seems to be the case in most other idl files.

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

Nice catch, thanks!

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

 
   /**
    * 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);
 
   /**
    * 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").
-   * 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);
 
   /**
    * 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 is

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

s/is/was
or even better:
s/is successful or not/succeeded

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

Done.

+   * successful or not.
    */
   PP_Bool DescribeAsIPv4Address([in] PP_Resource addr,
                                 [out] 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 is
+   * successful or not.

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

As above.

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

Done.

    */
   PP_Bool DescribeAsIPv6Address([in] PP_Resource addr,
                                 [out] PP_NetAddress_IPv6_Dev ipv6_addr);
 };