Update comments of the Pepper networking APIs.

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

Committed: https://src.chromium.org/viewvc/chrome?view=rev&revision=208037

[yzshen1, 2013-06-20 07:04:38]

Hi, Bill and David.

Would you please take a look? Thanks!

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

Comments on IDL

https://codereview.chromium.org/16938011/diff/1/ppapi/api/dev/ppb_host_resolv...
File ppapi/api/dev/ppb_host_resolver_dev.idl (right):

https://codereview.chromium.org/16938011/diff/1/ppapi/api/dev/ppb_host_resolv...
ppapi/api/dev/ppb_host_resolver_dev.idl:18: * be OR-ed and passed to the host
resolver. Currently there is only one flag
I think the last sentence is unnecessary.

https://codereview.chromium.org/16938011/diff/1/ppapi/api/dev/ppb_host_resolv...
ppapi/api/dev/ppb_host_resolver_dev.idl:24: * Requests the canonical name of the
host, which can be retrieved by
s/Requests/Hint to request/

https://codereview.chromium.org/16938011/diff/1/ppapi/api/dev/ppb_host_resolv...
ppapi/api/dev/ppb_host_resolver_dev.idl:78: * Requests to resolve a host name.
When the call completes successfully, the
s/Requests to resolve/Requests resolution of/
s/When/If

https://codereview.chromium.org/16938011/diff/1/ppapi/api/dev/ppb_host_resolv...
ppapi/api/dev/ppb_host_resolver_dev.idl:95: * returned if the host name couldn't
be resolved.
PP_ERROR_FAILED on other browser errors, correct?

https://codereview.chromium.org/16938011/diff/1/ppapi/api/dev/ppb_host_resolv...
ppapi/api/dev/ppb_host_resolver_dev.idl:110: * if
<code>PP_HOSTRESOLVER_FLAGS_CANONNAME</code> is not specified when
s/specified/set in the hint flags/

https://codereview.chromium.org/16938011/diff/1/ppapi/api/dev/ppb_net_address...
File ppapi/api/dev/ppb_net_address_dev.idl (right):

https://codereview.chromium.org/16938011/diff/1/ppapi/api/dev/ppb_net_address...
ppapi/api/dev/ppb_net_address_dev.idl:104: PP_Bool IsNetAddress([in] PP_Resource
addr);
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.

https://codereview.chromium.org/16938011/diff/1/ppapi/api/dev/ppb_net_address...
ppapi/api/dev/ppb_net_address_dev.idl:146: * @return A <code>PP_Bool</code>
value indicating whether the operation is
s/is/was
or even better:
s/is successful or not/succeeded

https://codereview.chromium.org/16938011/diff/1/ppapi/api/dev/ppb_net_address...
ppapi/api/dev/ppb_net_address_dev.idl:165: * successful or not.
As above.

https://codereview.chromium.org/16938011/diff/1/ppapi/api/dev/ppb_tcp_socket_...
File ppapi/api/dev/ppb_tcp_socket_dev.idl (right):

https://codereview.chromium.org/16938011/diff/1/ppapi/api/dev/ppb_tcp_socket_...
ppapi/api/dev/ppb_tcp_socket_dev.idl:17: * Option types used by
<code>SetOption()</code>.
s/types/names

https://codereview.chromium.org/16938011/diff/1/ppapi/api/dev/ppb_tcp_socket_...
ppapi/api/dev/ppb_tcp_socket_dev.idl:22: * Disables coalescing of small writes
to make TCP segments, and instead
s/Disables/Disable
this is to match 'deliver' later on.

https://codereview.chromium.org/16938011/diff/1/ppapi/api/dev/ppb_tcp_socket_...
ppapi/api/dev/ppb_tcp_socket_dev.idl:23: * deliver data immediately. Value type
is <code>PP_VARTYPE_BOOL</code>.
s/Value type is/Value's type should be
to match UDP docs.

https://codereview.chromium.org/16938011/diff/1/ppapi/api/dev/ppb_tcp_socket_...
ppapi/api/dev/ppb_tcp_socket_dev.idl:29: * Specifies the socket send buffer in
bytes. Value's type should be
nit s/buffer/buffer size
Here and below. Or better, why not copy the comment from the UDP flag
definitions.

https://codereview.chromium.org/16938011/diff/1/ppapi/api/dev/ppb_tcp_socket_...
ppapi/api/dev/ppb_tcp_socket_dev.idl:35: * successfully set, the browser doesn't
guarantee to conform to it.
s/to/it will

https://codereview.chromium.org/16938011/diff/1/ppapi/api/dev/ppb_tcp_socket_...
ppapi/api/dev/ppb_tcp_socket_dev.idl:46: * successfully set, the browser doesn't
guarantee to conform to it.
s/to/it will

https://codereview.chromium.org/16938011/diff/1/ppapi/api/dev/ppb_tcp_socket_...
ppapi/api/dev/ppb_tcp_socket_dev.idl:130: * Reads data from the socket. It can
only be called after a successful
s/It can/It should
because you can call it, but it would fail.

https://codereview.chromium.org/16938011/diff/1/ppapi/api/dev/ppb_tcp_socket_...
ppapi/api/dev/ppb_tcp_socket_dev.idl:151: * Writes data to the socket. It can
only be called after a successful
s/It can/It should

https://codereview.chromium.org/16938011/diff/1/ppapi/api/dev/ppb_tcp_socket_...
ppapi/api/dev/ppb_tcp_socket_dev.idl:170: * Cancels all pending reads and
writes, disconnects the socket. Any pending
s/,/and

https://codereview.chromium.org/16938011/diff/1/ppapi/api/dev/ppb_tcp_socket_...
ppapi/api/dev/ppb_tcp_socket_dev.idl:172: * pending IO was interrupted. After a
call to this method, any output buffers
A little awkward. How about:
After a call to this method, no output buffer pointers passed into previous
<code>Read()</code> calls will be accessed.

https://codereview.chromium.org/16938011/diff/1/ppapi/api/dev/ppb_udp_socket_...
File ppapi/api/dev/ppb_udp_socket_dev.idl (right):

https://codereview.chromium.org/16938011/diff/1/ppapi/api/dev/ppb_udp_socket_...
ppapi/api/dev/ppb_udp_socket_dev.idl:91: * Binds to the given address.
s/Binds/Binds the socket/

https://codereview.chromium.org/16938011/diff/1/ppapi/api/dev/ppb_udp_socket_...
ppapi/api/dev/ppb_udp_socket_dev.idl:109: * Get the address that the socket has
bound to. It can only be called after
s/Get/Gets

https://codereview.chromium.org/16938011/diff/1/ppapi/api/dev/ppb_udp_socket_...
ppapi/api/dev/ppb_udp_socket_dev.idl:128: * @param[in] num_bytes The number of
bytes to read.
s/read/receive to be consistent with 'Receives' above and 'received' below.

https://codereview.chromium.org/16938011/diff/1/ppapi/api/dev/ppb_udp_socket_...
ppapi/api/dev/ppb_udp_socket_dev.idl:144: * Sends data to a specific
destination. It can only be called after a
s/destination/target address
or change 'target address' below to 'destination address'.

https://codereview.chromium.org/16938011/diff/1/ppapi/api/dev/ppb_udp_socket_...
ppapi/api/dev/ppb_udp_socket_dev.idl:170: * pending IO was interrupted. After a
call to this method, any output
A little awkward. How about:
After a call to this method, no output buffer pointers passed into previous
<code>RecvFrom()</code> calls will be accessed.

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

Thanks, Bill!
Please take another look.

https://codereview.chromium.org/16938011/diff/1/ppapi/api/dev/ppb_host_resolv...
File ppapi/api/dev/ppb_host_resolver_dev.idl (right):

https://codereview.chromium.org/16938011/diff/1/ppapi/api/dev/ppb_host_resolv...
ppapi/api/dev/ppb_host_resolver_dev.idl:18: * be OR-ed and passed to the host
resolver. Currently there is only one flag
According to offline discussion, I will keep it as it is.
Thanks!

On 2013/06/20 17:38:27, bbudge1 wrote:
> I think the last sentence is unnecessary.

https://codereview.chromium.org/16938011/diff/1/ppapi/api/dev/ppb_host_resolv...
ppapi/api/dev/ppb_host_resolver_dev.idl:24: * Requests the canonical name of the
host, which can be retrieved by
On 2013/06/20 17:38:27, bbudge1 wrote:
> s/Requests/Hint to request/

Done.

https://codereview.chromium.org/16938011/diff/1/ppapi/api/dev/ppb_host_resolv...
ppapi/api/dev/ppb_host_resolver_dev.idl:78: * Requests to resolve a host name.
When the call completes successfully, the
On 2013/06/20 17:38:27, bbudge1 wrote:
> s/Requests to resolve/Requests resolution of/
> s/When/If

Done.

https://codereview.chromium.org/16938011/diff/1/ppapi/api/dev/ppb_host_resolv...
ppapi/api/dev/ppb_host_resolver_dev.idl:95: * returned if the host name couldn't
be resolved.
There are quite a few, for example, FAILED, INPROGRESS, BADARGUMENT,
BADRESOURCE, etc. I think we don't have to mention all of those common ones.
What do you think?
On 2013/06/20 17:38:27, bbudge1 wrote:
> PP_ERROR_FAILED on other browser errors, correct?

https://codereview.chromium.org/16938011/diff/1/ppapi/api/dev/ppb_host_resolv...
ppapi/api/dev/ppb_host_resolver_dev.idl:110: * if
<code>PP_HOSTRESOLVER_FLAGS_CANONNAME</code> is not specified when
On 2013/06/20 17:38:27, bbudge1 wrote:
> s/specified/set in the hint flags/

Done.

https://codereview.chromium.org/16938011/diff/1/ppapi/api/dev/ppb_net_address...
File ppapi/api/dev/ppb_net_address_dev.idl (right):

https://codereview.chromium.org/16938011/diff/1/ppapi/api/dev/ppb_net_address...
ppapi/api/dev/ppb_net_address_dev.idl:104: PP_Bool IsNetAddress([in] PP_Resource
addr);
Nice catch, thanks!

On 2013/06/20 17:38:27, bbudge1 wrote:
> 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.

https://codereview.chromium.org/16938011/diff/1/ppapi/api/dev/ppb_net_address...
ppapi/api/dev/ppb_net_address_dev.idl:146: * @return A <code>PP_Bool</code>
value indicating whether the operation is
On 2013/06/20 17:38:27, bbudge1 wrote:
> s/is/was
> or even better:
> s/is successful or not/succeeded

Done.

https://codereview.chromium.org/16938011/diff/1/ppapi/api/dev/ppb_net_address...
ppapi/api/dev/ppb_net_address_dev.idl:165: * successful or not.
On 2013/06/20 17:38:27, bbudge1 wrote:
> As above.

Done.

https://codereview.chromium.org/16938011/diff/1/ppapi/api/dev/ppb_tcp_socket_...
File ppapi/api/dev/ppb_tcp_socket_dev.idl (right):

https://codereview.chromium.org/16938011/diff/1/ppapi/api/dev/ppb_tcp_socket_...
ppapi/api/dev/ppb_tcp_socket_dev.idl:17: * Option types used by
<code>SetOption()</code>.
On 2013/06/20 17:38:27, bbudge1 wrote:
> s/types/names

Done.

https://codereview.chromium.org/16938011/diff/1/ppapi/api/dev/ppb_tcp_socket_...
ppapi/api/dev/ppb_tcp_socket_dev.idl:22: * Disables coalescing of small writes
to make TCP segments, and instead
May I change 'deliver' to 'delivers'?
We usually use third-person singular for comments (such as line 29 'specifies').

On 2013/06/20 17:38:27, bbudge1 wrote:
> s/Disables/Disable
> this is to match 'deliver' later on.

https://codereview.chromium.org/16938011/diff/1/ppapi/api/dev/ppb_tcp_socket_...
ppapi/api/dev/ppb_tcp_socket_dev.idl:23: * deliver data immediately. Value type
is <code>PP_VARTYPE_BOOL</code>.
On 2013/06/20 17:38:27, bbudge1 wrote:
> s/Value type is/Value's type should be
> to match UDP docs.

Done.

https://codereview.chromium.org/16938011/diff/1/ppapi/api/dev/ppb_tcp_socket_...
ppapi/api/dev/ppb_tcp_socket_dev.idl:29: * Specifies the socket send buffer in
bytes. Value's type should be
On 2013/06/20 17:38:27, bbudge1 wrote:
> nit s/buffer/buffer size
> Here and below. Or better, why not copy the comment from the UDP flag
> definitions.

Done.

https://codereview.chromium.org/16938011/diff/1/ppapi/api/dev/ppb_tcp_socket_...
ppapi/api/dev/ppb_tcp_socket_dev.idl:35: * successfully set, the browser doesn't
guarantee to conform to it.
On 2013/06/20 17:38:27, bbudge1 wrote:
> s/to/it will

Done.

https://codereview.chromium.org/16938011/diff/1/ppapi/api/dev/ppb_tcp_socket_...
ppapi/api/dev/ppb_tcp_socket_dev.idl:46: * successfully set, the browser doesn't
guarantee to conform to it.
On 2013/06/20 17:38:27, bbudge1 wrote:
> s/to/it will

Done.

https://codereview.chromium.org/16938011/diff/1/ppapi/api/dev/ppb_tcp_socket_...
ppapi/api/dev/ppb_tcp_socket_dev.idl:130: * Reads data from the socket. It can
only be called after a successful
I have changed to "the socket must be connected" as we discussed.

On 2013/06/20 17:38:27, bbudge1 wrote:
> s/It can/It should
> because you can call it, but it would fail.

https://codereview.chromium.org/16938011/diff/1/ppapi/api/dev/ppb_tcp_socket_...
ppapi/api/dev/ppb_tcp_socket_dev.idl:151: * Writes data to the socket. It can
only be called after a successful
I have changed to "the socket must be connected" as we discussed.
On 2013/06/20 17:38:27, bbudge1 wrote:
> s/It can/It should

https://codereview.chromium.org/16938011/diff/1/ppapi/api/dev/ppb_tcp_socket_...
ppapi/api/dev/ppb_tcp_socket_dev.idl:170: * Cancels all pending reads and
writes, disconnects the socket. Any pending
On 2013/06/20 17:38:27, bbudge1 wrote:
> s/,/and

Done.

https://codereview.chromium.org/16938011/diff/1/ppapi/api/dev/ppb_tcp_socket_...
ppapi/api/dev/ppb_tcp_socket_dev.idl:172: * pending IO was interrupted. After a
call to this method, any output buffers
yeah, it sounds much better. Thanks!
On 2013/06/20 17:38:27, bbudge1 wrote:
> A little awkward. How about:
> After a call to this method, no output buffer pointers passed into previous
> <code>Read()</code> calls will be accessed.

https://codereview.chromium.org/16938011/diff/1/ppapi/api/dev/ppb_udp_socket_...
File ppapi/api/dev/ppb_udp_socket_dev.idl (right):

https://codereview.chromium.org/16938011/diff/1/ppapi/api/dev/ppb_udp_socket_...
ppapi/api/dev/ppb_udp_socket_dev.idl:91: * Binds to the given address.
On 2013/06/20 17:38:27, bbudge1 wrote:
> s/Binds/Binds the socket/

Done.

https://codereview.chromium.org/16938011/diff/1/ppapi/api/dev/ppb_udp_socket_...
ppapi/api/dev/ppb_udp_socket_dev.idl:109: * Get the address that the socket has
bound to. It can only be called after
On 2013/06/20 17:38:27, bbudge1 wrote:
> s/Get/Gets

Done.

https://codereview.chromium.org/16938011/diff/1/ppapi/api/dev/ppb_udp_socket_...
ppapi/api/dev/ppb_udp_socket_dev.idl:128: * @param[in] num_bytes The number of
bytes to read.
On 2013/06/20 17:38:27, bbudge1 wrote:
> s/read/receive to be consistent with 'Receives' above and 'received' below.

Done.

https://codereview.chromium.org/16938011/diff/1/ppapi/api/dev/ppb_udp_socket_...
ppapi/api/dev/ppb_udp_socket_dev.idl:144: * Sends data to a specific
destination. It can only be called after a
On 2013/06/20 17:38:27, bbudge1 wrote:
> s/destination/target address
> or change 'target address' below to 'destination address'.

Done.

https://codereview.chromium.org/16938011/diff/1/ppapi/api/dev/ppb_udp_socket_...
ppapi/api/dev/ppb_udp_socket_dev.idl:170: * pending IO was interrupted. After a
call to this method, any output
Because the output parameters also include PP_Resource pointers, I changed the
sentence to "no output parameters passed into..."

Thanks!
On 2013/06/20 17:38:27, bbudge1 wrote:
> A little awkward. How about:
> After a call to this method, no output buffer pointers passed into previous
> <code>RecvFrom()</code> calls will be accessed.

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

Looking good. Just spelling and grammatical nits

https://codereview.chromium.org/16938011/diff/1/ppapi/api/dev/ppb_host_resolv...
File ppapi/api/dev/ppb_host_resolver_dev.idl (right):

https://codereview.chromium.org/16938011/diff/1/ppapi/api/dev/ppb_host_resolv...
ppapi/api/dev/ppb_host_resolver_dev.idl:95: * returned if the host name couldn't
be resolved.
OK

https://codereview.chromium.org/16938011/diff/1/ppapi/api/dev/ppb_tcp_socket_...
File ppapi/api/dev/ppb_tcp_socket_dev.idl (right):

https://codereview.chromium.org/16938011/diff/1/ppapi/api/dev/ppb_tcp_socket_...
ppapi/api/dev/ppb_tcp_socket_dev.idl:22: * Disables coalescing of small writes
to make TCP segments, and instead
OK

https://codereview.chromium.org/16938011/diff/7001/ppapi/api/dev/ppb_tcp_sock...
File ppapi/api/dev/ppb_tcp_socket_dev.idl (right):

https://codereview.chromium.org/16938011/diff/7001/ppapi/api/dev/ppb_tcp_sock...
ppapi/api/dev/ppb_tcp_socket_dev.idl:83: * Connects to the given address.
s/Connects/Connects the socket

https://codereview.chromium.org/16938011/diff/7001/ppapi/api/dev/ppb_udp_sock...
File ppapi/api/dev/ppb_udp_socket_dev.idl (right):

https://codereview.chromium.org/16938011/diff/7001/ppapi/api/dev/ppb_udp_sock...
ppapi/api/dev/ppb_udp_socket_dev.idl:168: * pending IO was interrupted. After a
call to this method, not output
s/not/no

https://codereview.chromium.org/16938011/diff/7001/ppapi/cpp/dev/host_resolve...
File ppapi/cpp/dev/host_resolver_dev.h (right):

https://codereview.chromium.org/16938011/diff/7001/ppapi/cpp/dev/host_resolve...
ppapi/cpp/dev/host_resolver_dev.h:32: /// A contructor used to create a
<code>HostResolver_Dev</code> object.
s/contructor/constructor

https://codereview.chromium.org/16938011/diff/7001/ppapi/cpp/dev/host_resolve...
ppapi/cpp/dev/host_resolver_dev.h:39: /// return value that has already been
added 1 ref for you.
s/been added 1 ref for you/had 1 ref added for you

https://codereview.chromium.org/16938011/diff/7001/ppapi/cpp/dev/host_resolve...
ppapi/cpp/dev/host_resolver_dev.h:52: /// The assign operator for
<code>HostResolver_Dev</code>.
s/assign/assignment

https://codereview.chromium.org/16938011/diff/7001/ppapi/cpp/dev/host_resolve...
ppapi/cpp/dev/host_resolver_dev.h:59: /// Static function for determining
whether the browser supports the required
s/required//

https://codereview.chromium.org/16938011/diff/7001/ppapi/cpp/dev/net_address_...
File ppapi/cpp/dev/net_address_dev.h (right):

https://codereview.chromium.org/16938011/diff/7001/ppapi/cpp/dev/net_address_...
ppapi/cpp/dev/net_address_dev.h:25: /// return value that has already been added
1 ref for you.
s/been added 1 ref for you/has had 1 ref added for you

https://codereview.chromium.org/16938011/diff/7001/ppapi/cpp/dev/net_address_...
ppapi/cpp/dev/net_address_dev.h:30: /// A contructor used to create a
<code>NetAddress_Dev</code> object with the
s/contructor/constructor

https://codereview.chromium.org/16938011/diff/7001/ppapi/cpp/dev/net_address_...
ppapi/cpp/dev/net_address_dev.h:39: /// A contructor used to create a
<code>NetAddress_Dev</code> object with the
s/contructor/constructor

https://codereview.chromium.org/16938011/diff/7001/ppapi/cpp/dev/net_address_...
ppapi/cpp/dev/net_address_dev.h:56: /// The assign operator for
<code>NetAddress_Dev</code>.
s/assign/assignment

https://codereview.chromium.org/16938011/diff/7001/ppapi/cpp/dev/net_address_...
ppapi/cpp/dev/net_address_dev.h:63: /// Static function for determining whether
the browser supports the required
s/required//

https://codereview.chromium.org/16938011/diff/7001/ppapi/cpp/dev/tcp_socket_d...
File ppapi/cpp/dev/tcp_socket_dev.h (right):

https://codereview.chromium.org/16938011/diff/7001/ppapi/cpp/dev/tcp_socket_d...
ppapi/cpp/dev/tcp_socket_dev.h:30: /// A contructor used to create a
<code>TCPSocket_Dev</code> object.
s/contructor/constructor

https://codereview.chromium.org/16938011/diff/7001/ppapi/cpp/dev/tcp_socket_d...
ppapi/cpp/dev/tcp_socket_dev.h:37: /// return value that has already been added
1 ref for you.
s/been added 1 ref/has had 1 ref added

https://codereview.chromium.org/16938011/diff/7001/ppapi/cpp/dev/tcp_socket_d...
ppapi/cpp/dev/tcp_socket_dev.h:50: /// The assign operator for
<code>TCPSocket_Dev</code>.
s/assign/assignment

https://codereview.chromium.org/16938011/diff/7001/ppapi/cpp/dev/tcp_socket_d...
ppapi/cpp/dev/tcp_socket_dev.h:57: /// Static function for determining whether
the browser supports the required
s/required//

https://codereview.chromium.org/16938011/diff/7001/ppapi/cpp/dev/tcp_socket_d...
ppapi/cpp/dev/tcp_socket_dev.h:63: /// Connects to the given address.
s/Connects/Connects the socket

https://codereview.chromium.org/16938011/diff/7001/ppapi/cpp/dev/tcp_socket_d...
ppapi/cpp/dev/tcp_socket_dev.h:138: /// Cancels all pending reads and writes,
disconnects the socket. Any pending
s/,/ and

https://codereview.chromium.org/16938011/diff/7001/ppapi/cpp/dev/tcp_socket_d...
ppapi/cpp/dev/tcp_socket_dev.h:152: /// @param[in] name The option type to set.
nit s/option type/option

https://codereview.chromium.org/16938011/diff/7001/ppapi/cpp/dev/udp_socket_d...
File ppapi/cpp/dev/udp_socket_dev.h (right):

https://codereview.chromium.org/16938011/diff/7001/ppapi/cpp/dev/udp_socket_d...
ppapi/cpp/dev/udp_socket_dev.h:34: /// A contructor used to create a
<code>UDPSocket_Dev</code> object.
s/contructor/constructor

https://codereview.chromium.org/16938011/diff/7001/ppapi/cpp/dev/udp_socket_d...
ppapi/cpp/dev/udp_socket_dev.h:54: /// The assign operator for
<code>UDPSocket_Dev</code>.
s/assign/assignment

https://codereview.chromium.org/16938011/diff/7001/ppapi/cpp/dev/udp_socket_d...
ppapi/cpp/dev/udp_socket_dev.h:61: /// Static function for determining whether
the browser supports the required
s/required//

https://codereview.chromium.org/16938011/diff/7001/ppapi/cpp/dev/udp_socket_d...
ppapi/cpp/dev/udp_socket_dev.h:80: /// Get the address that the socket has bound
to. The socket must be bound.
nit s/has/is

https://codereview.chromium.org/16938011/diff/7001/ppapi/cpp/dev/udp_socket_d...
ppapi/cpp/dev/udp_socket_dev.h:103: /// must be at least <code>num_bytes</code>
big.
I prefer the tcp socket comment:
/// @param[out] buffer The buffer to store the received data on success. It
/// must be at least as large as <code>num_bytes</code>.

https://codereview.chromium.org/16938011/diff/7001/ppapi/cpp/dev/udp_socket_d...
ppapi/cpp/dev/udp_socket_dev.h:147: /// @param[in] name The option type to set.
nit s/option type/option

[yzshen1, 2013-06-20 22:20:48]

Thanks, Bill!

Please take another look. :)

https://codereview.chromium.org/16938011/diff/7001/ppapi/api/dev/ppb_tcp_sock...
File ppapi/api/dev/ppb_tcp_socket_dev.idl (right):

https://codereview.chromium.org/16938011/diff/7001/ppapi/api/dev/ppb_tcp_sock...
ppapi/api/dev/ppb_tcp_socket_dev.idl:83: * Connects to the given address.
On 2013/06/20 21:02:32, bbudge1 wrote:
> s/Connects/Connects the socket

Done.

https://codereview.chromium.org/16938011/diff/7001/ppapi/api/dev/ppb_udp_sock...
File ppapi/api/dev/ppb_udp_socket_dev.idl (right):

https://codereview.chromium.org/16938011/diff/7001/ppapi/api/dev/ppb_udp_sock...
ppapi/api/dev/ppb_udp_socket_dev.idl:168: * pending IO was interrupted. After a
call to this method, not output
On 2013/06/20 21:02:32, bbudge1 wrote:
> s/not/no

Done.

https://codereview.chromium.org/16938011/diff/7001/ppapi/cpp/dev/host_resolve...
File ppapi/cpp/dev/host_resolver_dev.h (right):

https://codereview.chromium.org/16938011/diff/7001/ppapi/cpp/dev/host_resolve...
ppapi/cpp/dev/host_resolver_dev.h:32: /// A contructor used to create a
<code>HostResolver_Dev</code> object.
On 2013/06/20 21:02:32, bbudge1 wrote:
> s/contructor/constructor

Done.

https://codereview.chromium.org/16938011/diff/7001/ppapi/cpp/dev/host_resolve...
ppapi/cpp/dev/host_resolver_dev.h:39: /// return value that has already been
added 1 ref for you.
On 2013/06/20 21:02:32, bbudge1 wrote:
> s/been added 1 ref for you/had 1 ref added for you

Done.

https://codereview.chromium.org/16938011/diff/7001/ppapi/cpp/dev/host_resolve...
ppapi/cpp/dev/host_resolver_dev.h:52: /// The assign operator for
<code>HostResolver_Dev</code>.
On 2013/06/20 21:02:32, bbudge1 wrote:
> s/assign/assignment

Done.

https://codereview.chromium.org/16938011/diff/7001/ppapi/cpp/dev/host_resolve...
ppapi/cpp/dev/host_resolver_dev.h:59: /// Static function for determining
whether the browser supports the required
On 2013/06/20 21:02:32, bbudge1 wrote:
> s/required//

Done.

https://codereview.chromium.org/16938011/diff/7001/ppapi/cpp/dev/net_address_...
File ppapi/cpp/dev/net_address_dev.h (right):

https://codereview.chromium.org/16938011/diff/7001/ppapi/cpp/dev/net_address_...
ppapi/cpp/dev/net_address_dev.h:25: /// return value that has already been added
1 ref for you.
On 2013/06/20 21:02:32, bbudge1 wrote:
> s/been added 1 ref for you/has had 1 ref added for you

Done.

https://codereview.chromium.org/16938011/diff/7001/ppapi/cpp/dev/net_address_...
ppapi/cpp/dev/net_address_dev.h:30: /// A contructor used to create a
<code>NetAddress_Dev</code> object with the
On 2013/06/20 21:02:32, bbudge1 wrote:
> s/contructor/constructor

Done.

https://codereview.chromium.org/16938011/diff/7001/ppapi/cpp/dev/net_address_...
ppapi/cpp/dev/net_address_dev.h:39: /// A contructor used to create a
<code>NetAddress_Dev</code> object with the
On 2013/06/20 21:02:32, bbudge1 wrote:
> s/contructor/constructor

Done.

https://codereview.chromium.org/16938011/diff/7001/ppapi/cpp/dev/net_address_...
ppapi/cpp/dev/net_address_dev.h:56: /// The assign operator for
<code>NetAddress_Dev</code>.
On 2013/06/20 21:02:32, bbudge1 wrote:
> s/assign/assignment

Done.

https://codereview.chromium.org/16938011/diff/7001/ppapi/cpp/dev/net_address_...
ppapi/cpp/dev/net_address_dev.h:63: /// Static function for determining whether
the browser supports the required
On 2013/06/20 21:02:32, bbudge1 wrote:
> s/required//

Done.

https://codereview.chromium.org/16938011/diff/7001/ppapi/cpp/dev/tcp_socket_d...
File ppapi/cpp/dev/tcp_socket_dev.h (right):

https://codereview.chromium.org/16938011/diff/7001/ppapi/cpp/dev/tcp_socket_d...
ppapi/cpp/dev/tcp_socket_dev.h:30: /// A contructor used to create a
<code>TCPSocket_Dev</code> object.
On 2013/06/20 21:02:32, bbudge1 wrote:
> s/contructor/constructor

Done.

https://codereview.chromium.org/16938011/diff/7001/ppapi/cpp/dev/tcp_socket_d...
ppapi/cpp/dev/tcp_socket_dev.h:37: /// return value that has already been added
1 ref for you.
On 2013/06/20 21:02:32, bbudge1 wrote:
> s/been added 1 ref/has had 1 ref added

Done.

https://codereview.chromium.org/16938011/diff/7001/ppapi/cpp/dev/tcp_socket_d...
ppapi/cpp/dev/tcp_socket_dev.h:50: /// The assign operator for
<code>TCPSocket_Dev</code>.
On 2013/06/20 21:02:32, bbudge1 wrote:
> s/assign/assignment

Done.

https://codereview.chromium.org/16938011/diff/7001/ppapi/cpp/dev/tcp_socket_d...
ppapi/cpp/dev/tcp_socket_dev.h:57: /// Static function for determining whether
the browser supports the required
On 2013/06/20 21:02:32, bbudge1 wrote:
> s/required//

Done.

https://codereview.chromium.org/16938011/diff/7001/ppapi/cpp/dev/tcp_socket_d...
ppapi/cpp/dev/tcp_socket_dev.h:63: /// Connects to the given address.
On 2013/06/20 21:02:32, bbudge1 wrote:
> s/Connects/Connects the socket

Done.

https://codereview.chromium.org/16938011/diff/7001/ppapi/cpp/dev/tcp_socket_d...
ppapi/cpp/dev/tcp_socket_dev.h:138: /// Cancels all pending reads and writes,
disconnects the socket. Any pending
On 2013/06/20 21:02:32, bbudge1 wrote:
> s/,/ and

Done.

https://codereview.chromium.org/16938011/diff/7001/ppapi/cpp/dev/tcp_socket_d...
ppapi/cpp/dev/tcp_socket_dev.h:152: /// @param[in] name The option type to set.
On 2013/06/20 21:02:32, bbudge1 wrote:
> nit s/option type/option

Done.

https://codereview.chromium.org/16938011/diff/7001/ppapi/cpp/dev/udp_socket_d...
File ppapi/cpp/dev/udp_socket_dev.h (right):

https://codereview.chromium.org/16938011/diff/7001/ppapi/cpp/dev/udp_socket_d...
ppapi/cpp/dev/udp_socket_dev.h:34: /// A contructor used to create a
<code>UDPSocket_Dev</code> object.
On 2013/06/20 21:02:32, bbudge1 wrote:
> s/contructor/constructor

Done.

https://codereview.chromium.org/16938011/diff/7001/ppapi/cpp/dev/udp_socket_d...
ppapi/cpp/dev/udp_socket_dev.h:54: /// The assign operator for
<code>UDPSocket_Dev</code>.
On 2013/06/20 21:02:32, bbudge1 wrote:
> s/assign/assignment

Done.

https://codereview.chromium.org/16938011/diff/7001/ppapi/cpp/dev/udp_socket_d...
ppapi/cpp/dev/udp_socket_dev.h:61: /// Static function for determining whether
the browser supports the required
On 2013/06/20 21:02:32, bbudge1 wrote:
> s/required//

Done.

https://codereview.chromium.org/16938011/diff/7001/ppapi/cpp/dev/udp_socket_d...
ppapi/cpp/dev/udp_socket_dev.h:80: /// Get the address that the socket has bound
to. The socket must be bound.
On 2013/06/20 21:02:32, bbudge1 wrote:
> nit s/has/is

Done.

https://codereview.chromium.org/16938011/diff/7001/ppapi/cpp/dev/udp_socket_d...
ppapi/cpp/dev/udp_socket_dev.h:103: /// must be at least <code>num_bytes</code>
big.
On 2013/06/20 21:02:32, bbudge1 wrote:
> I prefer the tcp socket comment:
> /// @param[out] buffer The buffer to store the received data on success. It
> /// must be at least as large as <code>num_bytes</code>.

Done.

https://codereview.chromium.org/16938011/diff/7001/ppapi/cpp/dev/udp_socket_d...
ppapi/cpp/dev/udp_socket_dev.h:147: /// @param[in] name The option type to set.
On 2013/06/20 21:02:32, bbudge1 wrote:
> nit s/option type/option

Done.

[bbudge, 2013-06-20 22:32:28]

LGTM nice!

[dmichael (off chromium), 2013-06-21 21:33:03]

lgtm, thank you for doing this! (& sorry for slowness)

[yzshen1, 2013-06-21 21:33:47]

On 2013/06/21 21:33:03, dmichael wrote:
> lgtm, thank you for doing this! (& sorry for slowness)

Thanks a lot David! :)

[commit-bot: I haz the power, 2013-06-21 21:34:47]

CQ is trying da patch. Follow status at
https://chromium-status.appspot.com/cq/yzshen@chromium.org/16938011/18001

[commit-bot: I haz the power, 2013-06-21 21:34:52]

Failed to apply patch for ppapi/api/dev/ppb_host_resolver_dev.idl:
While running patch -p1 --forward --force --no-backup-if-mismatch;
  patching file ppapi/api/dev/ppb_host_resolver_dev.idl
  Hunk #2 FAILED at 14.
  Hunk #3 succeeded at 56 (offset -4 lines).
  1 out of 3 hunks FAILED -- saving rejects to file
ppapi/api/dev/ppb_host_resolver_dev.idl.rej

Patch:       ppapi/api/dev/ppb_host_resolver_dev.idl
Index: ppapi/api/dev/ppb_host_resolver_dev.idl
diff --git a/ppapi/api/dev/ppb_host_resolver_dev.idl
b/ppapi/api/dev/ppb_host_resolver_dev.idl
index
cf274341534625e603adb3dc0b463085073dfa47..fa5612bb7f3d26726e2a9c86e061d3006fecb286
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,44 +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.
+ * <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,
-  /**
-   * Hint to the resolver that only loopback addresses are configured.
-   */
-  PP_HOSTRESOLVER_FLAGS_LOOPBACK_ONLY = 1 << 1
+  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,
@@ -61,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);

[commit-bot: I haz the power, 2013-06-21 22:58:34]

CQ is trying da patch. Follow status at
https://chromium-status.appspot.com/cq/yzshen@chromium.org/16938011/31001

[commit-bot: I haz the power, 2013-06-22 02:32:49]

CQ is trying da patch. Follow status at
https://chromium-status.appspot.com/cq/yzshen@chromium.org/16938011/31001

[commit-bot: I haz the power, 2013-06-22 03:00:22]

CQ is trying da patch. Follow status at
https://chromium-status.appspot.com/cq/yzshen@chromium.org/16938011/31001

[commit-bot: I haz the power, 2013-06-22 03:30:43]

CQ is trying da patch. Follow status at
https://chromium-status.appspot.com/cq/yzshen@chromium.org/16938011/31001

[commit-bot: I haz the power, 2013-06-22 03:40:43]

CQ is trying da patch. Follow status at
https://chromium-status.appspot.com/cq/yzshen@chromium.org/16938011/31001

[commit-bot: I haz the power, 2013-06-22 14:29:04]

Change committed as 208037