Improve documentation on duplex.rs

src/libsync/comm/duplex.rs

@@ -14,20 +14,32 @@ Higher level communication abstractions.
 
 */
 
-#![allow(missing_doc)]
-
 use core::prelude::*;
 
 use comm;
 use comm::{Sender, Receiver, channel};
 
-/// An extension of `pipes::stream` that allows both sending and receiving.
+/// An extension of `pipes::stream` that allows both sending and receiving
+/// data over two channels
 pub struct DuplexStream<S, R> {
     tx: Sender<S>,
     rx: Receiver<R>,
 }
 
 /// Creates a bidirectional stream.
+///
+/// # Example
+/// ```
+/// use std::comm;
+///
+/// let (left, right) = comm::duplex();
+///
+/// left.send(("ABC").to_string());
+/// right.send(123);
+///
+/// assert!(left.recv() == 123);
+/// assert!(right.recv() == "ABC".to_string());
+/// ```
 pub fn duplex<S: Send, R: Send>() -> (DuplexStream<S, R>, DuplexStream<R, S>) {
     let (tx1, rx1) = channel();
     let (tx2, rx2) = channel();
@@ -37,18 +49,44 @@ pub fn duplex<S: Send, R: Send>() -> (DuplexStream<S, R>, DuplexStream<R, S>) {
 
 // Allow these methods to be used without import:
 impl<S:Send,R:Send> DuplexStream<S, R> {
+    /// Send data over the channel.
     pub fn send(&self, x: S) {
         self.tx.send(x)
     }
+
+    /// Optionally send data to the channel.
+    ///
+    /// # Example
+    /// ```
+    /// use std::comm;
+    /// let (left, right) = comm::duplex();
+    /// left.send("ABC".to_string());
+    /// spawn(proc() {
+    ///     right.send(123);
+    ///     assert!(right.recv() == "ABC".to_string());
+    ///     drop(right);
+    /// });
+    /// assert!(left.recv() == 123);
+    /// // I force this task to wait because the other have to drop.
+    /// std::io::timer::sleep(1000);
+    /// assert_eq!(left.send_opt("ABC".to_string()),
+    ///                          Err("ABC".to_string()));
+    /// ```
     pub fn send_opt(&self, x: S) -> Result<(), S> {
         self.tx.send_opt(x)
     }
+
+    /// Receive data from the channel.
     pub fn recv(&self) -> R {
         self.rx.recv()
     }
+
+    /// Try to receive data from the channel.
     pub fn try_recv(&self) -> Result<R, comm::TryRecvError> {
         self.rx.try_recv()
     }
+
+    /// Optionally receive data from the channel.
     pub fn recv_opt(&self) -> Result<R, ()> {
         self.rx.recv_opt()
     }