-/*!
- * Utilities for managing and scheduling tasks
- *
- * An executing Rust program consists of a collection of tasks, each with their
- * own stack, and sole ownership of their allocated heap data. Tasks communicate
- * with each other using channels (see `std::comm` for more info about how
- * communication works).
- *
- * Failure in one task does not propagate to any others (not to parent, not to
- * child). Failure propagation is instead handled by using the channel send()
- * and recv() methods which will fail if the other end has hung up already.
- *
- * Task Scheduling:
- *
- * By default, every task is created with the same "flavor" as the calling task.
- * This flavor refers to the scheduling mode, with two possibilities currently
- * being 1:1 and M:N modes. Green (M:N) tasks are cooperatively scheduled and
- * native (1:1) tasks are scheduled by the OS kernel.
- *
- * # Example
- *
- * ```rust
- * spawn(proc() {
- * println!("Hello, World!");
- * })
- * ```
- */
+//! Utilities for managing and scheduling tasks
+//!
+//! An executing Rust program consists of a collection of lightweight tasks,
+//! each with their own stack. Tasks communicate with each other using channels
+//! (see `std::comm`) or other forms of synchronization (see `std::sync`) that
+//! ensure data-race freedom.
+//!
+//! Failure in one task does immediately propagate to any others (not to parent,
+//! not to child). Failure propagation is instead handled as part of task
+//! synchronization. For example, the channel `send()` and `recv()` methods will
+//! fail if the other end has hung up already.
+//!
+//! # Basic task scheduling
+//!
+//! By default, every task is created with the same "flavor" as the calling task.
+//! This flavor refers to the scheduling mode, with two possibilities currently
+//! being 1:1 and M:N modes. Green (M:N) tasks are cooperatively scheduled and
+//! native (1:1) tasks are scheduled by the OS kernel.
+//!
+//! ## Example
+//!
+//! ```rust
+//! spawn(proc() {
+//! println!("Hello, World!");
+//! })
+//! ```
+//!
+//! # Advanced task scheduling
+//!
+//! Task spawning can also be configured to use a particular scheduler, to
+//! redirect the new task's output, or to yield a `future` representing the
+//! task's final result. The configuration is established using the
+//! `TaskBuilder` API:
+//!
+//! ## Example
+//!
+//! ```rust
+//! extern crate green;
+//! extern crate native;
+//!
+//! use std::task::TaskBuilder;
+//! use green::{SchedPool, PoolConfig, GreenTaskBuilder};
+//! use native::NativeTaskBuilder;
+//!
+//! # fn main() {
+//! // Create a green scheduler pool with the default configuration
+//! let mut pool = SchedPool::new(PoolConfig::new());
+//!
+//! // Spawn a task in the green pool
+//! let mut fut_green = TaskBuilder::new().green(&mut pool).try_future(proc() {
+//! /* ... */
+//! });
+//!
+//! // Spawn a native task
+//! let mut fut_native = TaskBuilder::new().native().try_future(proc() {
+//! /* ... */
+//! });
+//!
+//! // Wait for both tasks to finish, recording their outcome
+//! let res_green = fut_green.unwrap();
+//! let res_native = fut_native.unwrap();
+//!
+//! // Shut down the green scheduler pool
+//! pool.shutdown();
+//! # }
+//! ```