More concrete pair documentation and example

This commit adds an example about `pair` and adds some documentation
about.

This commit was made in response to
berkowski#25.

Cargo.toml

@@ -26,6 +26,6 @@ mio-serial = { version = "3.3.0", default-features = false }
 
 [dev-dependencies]
 futures = "0.3.1"
-tokio = { version = "0.2.0", features = ["macros"], default-features = false }
+tokio = { version = "0.2.0", features = ["io-util", "macros", "rt-core"], default-features = false }
 tokio-util = { version = "0.2.0", features = ["codec"], default-features = false }
 bytes = "0.5"

examples/pair.rs

@@ -0,0 +1,33 @@
+use tokio::io::{AsyncReadExt, AsyncWriteExt};
+use tokio_serial::Serial;
+
+#[tokio::main]
+async fn main() -> std::io::Result<()> {
+    let (mut req, mut res) = Serial::pair()?;
+
+    let f = tokio::spawn(async move {
+        let mut buffer = [0u8; 1];
+        res.read_exact(&mut buffer).await?;
+
+        let [command] = buffer;
+        assert_eq!(command, 1);
+
+        res.write_all(&buffer).await?;
+        res.shutdown().await?;
+
+        std::io::Result::<_>::Ok(())
+    });
+    // Write something
+    req.write_all(&[1u8]).await?;
+    // Read the answer
+    let mut buffer = [0u8; 1];
+    req.read_exact(&mut buffer).await?;
+
+    let [response] = buffer;
+    assert_eq!(response, 1);
+
+    // may be a join error, or an IO error from inside the task
+    f.await??;
+
+    Ok(())
+}

examples/serial_println.rs

@@ -1,8 +1,8 @@
 #![warn(rust_2018_idioms)]
 
+use futures::stream::StreamExt;
 use std::{env, io, str};
 use tokio_util::codec::{Decoder, Encoder};
-use futures::stream::StreamExt;
 
 use bytes::BytesMut;
 

src/lib.rs

@@ -47,9 +47,16 @@ impl Serial {
     /// Two connected, unnamed `Serial` objects.
     ///
     /// ## Errors
-    /// Attempting any IO or parameter settings on the slave tty after the master
+    /// Attempting any IO or parameter settings on the second tty after the first
     /// tty is closed will return errors.
     ///
+    /// ## Examples
+    ///
+    /// ```
+    /// use tokio_serial::Serial;
+    ///
+    /// let (fst, snd) = Serial::pair().unwrap();
+    /// ```
     #[cfg(unix)]
     pub fn pair() -> Result<(Self, Self)> {
         let (master, slave) = mio_serial::Serial::pair()?;
@@ -218,23 +225,27 @@ impl AsRawFd for Serial {
 impl AsyncRead for Serial {
     fn poll_read(
         self: Pin<&mut Self>,
-        cx: &mut Context <'_>,
+        cx: &mut Context<'_>,
         buf: &mut [u8],
     ) -> Poll<io::Result<usize>> {
         Pin::new(&mut self.get_mut().io).poll_read(cx, buf)
     }
 }
 
 impl AsyncWrite for Serial {
-    fn poll_write(self: Pin<&mut Self>, cx: &mut Context <'_>, buf: &[u8]) -> Poll<io::Result<usize>> {
+    fn poll_write(
+        self: Pin<&mut Self>,
+        cx: &mut Context<'_>,
+        buf: &[u8],
+    ) -> Poll<io::Result<usize>> {
         Pin::new(&mut self.get_mut().io).poll_write(cx, buf)
     }
 
-    fn poll_flush(self: Pin<&mut Self>, cx: &mut Context <'_>) -> Poll<io::Result<()>> {
+    fn poll_flush(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<io::Result<()>> {
         Pin::new(&mut self.get_mut().io).poll_flush(cx)
     }
 
-    fn poll_shutdown(self: Pin<&mut Self>, cx: &mut Context <'_>) -> Poll<io::Result<()>> {
+    fn poll_shutdown(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<io::Result<()>> {
         Pin::new(&mut self.get_mut().io).poll_shutdown(cx)
     }
 }