Making comments on MojoReadMessage a little easier to read.

Making comments on MojoReadMessage a little easier to read.

The existing comment was pretty good but I did have to re-read some parts of it a couple times to get the right understanding. I had some confusion over some parts that looked like a division but were actually a slash. I was also a bit confused about which message was being referred to as the "next message" in some parts of the docs.

R=viettrungluu@chromium.org

Committed: https://chromium.googlesource.com/external/mojo/+/d043808fd0bd58390c849d54be6dcac99eb9aae9

[ggowan, 2015-01-19 18:20:52]

ggowan@google.com changed reviewers:
+ viettrungluu@chromium.org

[viettrungluu, 2015-01-30 22:23:57]

https://codereview.chromium.org/863473004/diff/1/mojo/public/c/system/message...
File mojo/public/c/system/message_pipe.h (right):

https://codereview.chromium.org/863473004/diff/1/mojo/public/c/system/message...
mojo/public/c/system/message_pipe.h:136: // its entirety or it will not be read
at all.  If the message is too large, it
nit: one space after '.'

https://codereview.chromium.org/863473004/diff/1/mojo/public/c/system/message...
mojo/public/c/system/message_pipe.h:142: // |num_bytes| and |num_handles| are
in/out parameters that on input must be set
You should probably say "optional in/out"; otherwise you're burying the lede.

https://codereview.chromium.org/863473004/diff/1/mojo/public/c/system/message...
mojo/public/c/system/message_pipe.h:144: // to the actual number of bytes or
handles contained in the message.  Either
...

https://codereview.chromium.org/863473004/diff/1/mojo/public/c/system/message...
mojo/public/c/system/message_pipe.h:150: // |bytes| and |handles| are output
arrays that will receive the contents of the
This paragraph is overly verbose.

[ggowan, 2015-01-30 22:43:08]

Thanks! Comments addressed. PTAL

https://codereview.chromium.org/863473004/diff/1/mojo/public/c/system/message...
File mojo/public/c/system/message_pipe.h (right):

https://codereview.chromium.org/863473004/diff/1/mojo/public/c/system/message...
mojo/public/c/system/message_pipe.h:136: // its entirety or it will not be read
at all.  If the message is too large, it
On 2015/01/30 22:23:57, viettrungluu wrote:
> nit: one space after '.'

Done.

https://codereview.chromium.org/863473004/diff/1/mojo/public/c/system/message...
mojo/public/c/system/message_pipe.h:142: // |num_bytes| and |num_handles| are
in/out parameters that on input must be set
On 2015/01/30 22:23:57, viettrungluu wrote:
> You should probably say "optional in/out"; otherwise you're burying the lede.

Done.

https://codereview.chromium.org/863473004/diff/1/mojo/public/c/system/message...
mojo/public/c/system/message_pipe.h:144: // to the actual number of bytes or
handles contained in the message.  Either
On 2015/01/30 22:23:57, viettrungluu wrote:
> ...

Done.

https://codereview.chromium.org/863473004/diff/1/mojo/public/c/system/message...
mojo/public/c/system/message_pipe.h:150: // |bytes| and |handles| are output
arrays that will receive the contents of the
On 2015/01/30 22:23:57, viettrungluu wrote:
> This paragraph is overly verbose.

Trimmed. I moved some of this into previous paragraphs where it could be stated
more succinctly.

[viettrungluu, 2015-01-30 23:44:14]

LGTM w/some additional tightening.

https://codereview.chromium.org/863473004/diff/20001/mojo/public/c/system/mes...
File mojo/public/c/system/message_pipe.h (right):

https://codereview.chromium.org/863473004/diff/20001/mojo/public/c/system/mes...
mojo/public/c/system/message_pipe.h:135: // message if it cannot fit in the
provided buffers. The message must be read
nit: Again, this could be tighter: "The message will be read in its entirety or
not at all; if it is not, it will remain enqueued unless the
|MOJO_READ_MESSAGE_FLAG_MAY_DISCARD| flag was passed."

https://codereview.chromium.org/863473004/diff/20001/mojo/public/c/system/mes...
mojo/public/c/system/message_pipe.h:138: // |MOJO_READ_MESSAGE_FLAG_MAY_DISCARD|
flag is passed. Either way, at most one
"Either way ... with each call" seems redundant to me.

[ggowan, 2015-01-31 00:34:13]

Thanks for the review. Good feedback. I've addressed all your comments.

https://codereview.chromium.org/863473004/diff/20001/mojo/public/c/system/mes...
File mojo/public/c/system/message_pipe.h (right):

https://codereview.chromium.org/863473004/diff/20001/mojo/public/c/system/mes...
mojo/public/c/system/message_pipe.h:135: // message if it cannot fit in the
provided buffers. The message must be read
On 2015/01/30 23:44:13, viettrungluu wrote:
> nit: Again, this could be tighter: "The message will be read in its entirety
or
> not at all; if it is not, it will remain enqueued unless the
> |MOJO_READ_MESSAGE_FLAG_MAY_DISCARD| flag was passed."

Thanks, done.

https://codereview.chromium.org/863473004/diff/20001/mojo/public/c/system/mes...
mojo/public/c/system/message_pipe.h:138: // |MOJO_READ_MESSAGE_FLAG_MAY_DISCARD|
flag is passed. Either way, at most one
On 2015/01/30 23:44:13, viettrungluu wrote:
> "Either way ... with each call" seems redundant to me.

Removed those words.

[ggowan, 2015-01-31 00:36:10]

Committed patchset #3 (id:40001) manually as
d043808fd0bd58390c849d54be6dcac99eb9aae9 (presubmit successful).