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

4 files changed, 350 insertions, 5 deletions

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);