From 20e4f793e22e7078435259e8fe65ca60f92fec1c Mon Sep 17 00:00:00 2001
From: Brian Anderson <banderson@mozilla.com>
Date: Thu, 27 Oct 2011 11:15:28 -0700
Subject: [PATCH] More std docs

---
 src/lib/comm.rs | 24 +++++++++++++++++++++---
 src/lib/task.rs |  5 +++++
 2 files changed, 26 insertions(+), 3 deletions(-)

diff --git a/src/lib/comm.rs b/src/lib/comm.rs
index dca101b4e59a..9c8f20a9a752 100644
--- a/src/lib/comm.rs
+++ b/src/lib/comm.rs
@@ -56,9 +56,18 @@ type port_id = int;
 /*
 Type: chan
 
-A handle through which data may be sent.
+A communication endpoint that can send messages. Channels send
+messages to ports.
 
-Each channel is associated with a single <port>.
+Each channel is bound to a port when the channel is constructed, so
+the destination port for a channel must exist before the channel
+itself.
+
+Channels are weak: a channel does not keep the port it is bound to alive.
+If a channel attempts to send data to a dead port that data will be silently
+dropped.
+
+Channels may be duplicated and themselves transmitted over other channels.
 */
 tag chan<unique T> {
     chan_t(task::task, port_id);
@@ -72,7 +81,11 @@ resource port_ptr(po: *rustrt::rust_port) {
 /*
 Type: port
 
-A handle through which data may be received.
+A communication endpoint that can receive messages. Ports receive
+messages from channels.
+
+Each port has a unique per-task identity and may not be replicated or
+transmitted. If a port value is copied, both copies refer to the same port.
 
 Ports may be associated with multiple <chan>s.
 */
@@ -105,6 +118,9 @@ fn port<unique T>() -> port<T> {
 Function: recv
 
 Receive from a port.
+
+If no data is available on the port then the task will block until data
+becomes available.
 */
 fn recv<unique T>(p: port<T>) -> T { ret rusti::recv(***p) }
 
@@ -112,6 +128,8 @@ fn recv<unique T>(p: port<T>) -> T { ret rusti::recv(***p) }
 Function: chan
 
 Constructs a channel.
+
+The channel is bound to the port used to construct it.
 */
 fn chan<unique T>(p: port<T>) -> chan<T> {
     chan_t(task::get_task_id(), rustrt::get_port_id(***p))
diff --git a/src/lib/task.rs b/src/lib/task.rs
index 5470cb06c9c7..6f92ed7ff5e4 100644
--- a/src/lib/task.rs
+++ b/src/lib/task.rs
@@ -1,3 +1,8 @@
+/*
+Module: task
+
+Task management.
+*/
 import cast = unsafe::reinterpret_cast;
 import comm;
 import option::{some, none};