Improve docs for capnp::serialize::try_read_message and capnp_futures::serialize::read_message

Author: dwrensha

capnp-futures/src/serialize.rs

@@ -28,7 +28,10 @@ use capnp::serialize::{OwnedSegments, SegmentLengthsBuilder};
 
 use futures::{AsyncRead, AsyncReadExt, AsyncWrite, AsyncWriteExt};
 
-/// Begins an asynchronous read of a message from `reader`.
+/// Begins an asynchronous read of a message from `reader`. Returns `None` if
+/// `reader` has zero bytes left (i.e. is at end-of-file). To read a stream
+/// containing an unknown number of messages, you could call this function
+/// repeatedly until it returns `None`.
 pub async fn read_message<R>(mut reader: R, options: message::ReaderOptions) -> Result<Option<message::Reader<OwnedSegments>>>
     where R: AsyncRead + Unpin
 {

capnp/src/serialize.rs

@@ -191,9 +191,9 @@ where R: Read {
     read_segments(&mut read, owned_segments_builder.into_owned_segments(), options)
 }
 
-/// Like read_message(), but returns None instead of an error if there are zero bytes left in `read`.
-/// This is useful for reading a message stream of unknown length -- you call this function
-/// until it returns None.
+/// Like `read_message()`, but returns None instead of an error if there are zero bytes left in
+/// `read`. This is useful for reading a stream containing an unknown number of messages -- you
+/// call this function until it returns None.
 pub fn try_read_message<R>(mut read: R, options: message::ReaderOptions) -> Result<Option<message::Reader<OwnedSegments>>>
 where R: Read {
     let owned_segments_builder = match read_segment_table(&mut read, options)? {