Update the documentation.

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "termion"
-version = "1.0.7"
+version = "1.0.8"
 authors = ["ticki <Ticki@users.noreply.github.com>"]
 description = "A bindless library for manipulating terminals."
 repository = "https://github.com/ticki/termion"

README.md

@@ -1,6 +1,9 @@
 # Termion
 
-Termion is a pure Rust, bindless library for low-level handling, manipulating
+[Documentation](https://docs.rs/termion) | [Examples](https://github.com/Ticki/termion/tree/master/examples) | [Changelog](https://github.com/Ticki/termion/tree/master/CHANGELOG.md)
+|----|----|----
+
+**Termion** is a pure Rust, bindless library for low-level handling, manipulating
 and reading information about terminals. This provides a full-featured
 alternative to Termbox.
 
@@ -18,9 +21,6 @@ cleaner to use escapes.
 
 Supports Redox, Mac OS X, BSD, and Linux (or, in general, ANSI terminals).
 
-[Documentation](https://docs.rs/termion) | [Examples](https://github.com/Ticki/termion/tree/master/examples) | [Changelog](https://github.com/Ticki/termion/tree/master/CHANGELOG.md)
-|----|----|----
-
 ## A note on stability
 
 Although small breaking changes might happen, I will try my best to avoid them,

examples/async.rs

@@ -2,7 +2,7 @@ extern crate termion;
 
 use termion::raw::IntoRawMode;
 use termion::async_stdin;
-use std::io::{Read, Write, stdout, stdin};
+use std::io::{Read, Write, stdout};
 use std::thread;
 use std::time::Duration;
 

src/async.rs

@@ -28,10 +28,12 @@ pub fn async_stdin() -> AsyncReader {
 }
 
 /// An asynchronous reader.
+///
+/// This acts as any other stream, with the exception that reading from it won't block. Instead,
+/// the buffer will only be partially updated based on how much the internal buffer holds.
 pub struct AsyncReader {
     /// The underlying mpsc receiver.
-    #[doc(hidden)]
+    recv: mpsc::Receiver<io::Result<u8>>,
-    pub recv: mpsc::Receiver<io::Result<u8>>,
 }
 
 impl Read for AsyncReader {

src/color.rs

@@ -1,4 +1,18 @@
-//! Colors.
+//! Color managemement.
+//!
+//! # Example
+//!
+//! ```rust
+//! use termion::{color, style};
+//!
+//! use std::io;
+//!
+//! fn main() {
+//!     println!("{}Red", color::Fg(color::Red));
+//!     println!("{}Blue", color::Fg(color::Blue));
+//!     println!("{}Back again", color::Fg(color::Reset));
+//! }
+//! ```
 
 use std::fmt;
 

src/cursor.rs

@@ -1,4 +1,4 @@
-//! Cursor.
+//! Cursor movement.
 
 use std::fmt;
 
@@ -12,6 +12,16 @@ derive_csi_sequence!("Show the cursor.", Show, "?25h");
 /// ANSI escapes are very poorly designed, and one of the many odd aspects is being one-based. This
 /// can be quite strange at first, but it is not that big of an obstruction once you get used to
 /// it.
+///
+/// # Example
+///
+/// ```rust
+/// extern crate termion;
+///
+/// fn main() {
+///     print!("{}{}Stuff", termion::clear::All, termion::cursor::Goto(5, 3));
+/// }
+/// ```
 #[derive(Copy, Clone, PartialEq, Eq)]
 pub struct Goto(pub u16, pub u16);
 

src/input.rs

@@ -1,4 +1,4 @@
-//! Input.
+//! User input.
 
 use std::io::{self, Read, Write};
 use std::ops;

src/raw.rs

@@ -1,10 +1,34 @@
-//! Raw mode.
+//! Managing raw mode.
+//!
+//! Raw mode is a particular state a TTY can have. It signifies that:
+//!
+//! 1. No line buffering (the input is given byte-by-byte).
+//! 2. The input is not written out, instead it has to be done manually by the programmer.
+//! 3. The output is not canonicalized (for example, `\n` means "go one line down", not "line
+//!    break").
+//!
+//! It is essential to design terminal programs.
+//!
+//! # Example
+//!
+//! ```rust,ignore
+//! use termion::raw::IntoRawMode;
+//! use std::io::{Write, stdout};
+//!
+//! fn main() {
+//!     let mut stdout = stdout().into_raw_mode().unwrap();
+//!
+//!     write!(stdout, "Hey there.").unwrap();
+//! }
+//! ```
 
 use std::io::{self, Write};
 use std::ops;
 
 /// A terminal restorer, which keeps the previous state of the terminal, and restores it, when
 /// dropped.
+///
+/// Restoring will entirely bring back the old TTY state.
 #[cfg(target_os = "redox")]
 pub struct RawTerminal<W: Write> {
     output: W,
@@ -60,6 +84,11 @@ impl<W: Write> Write for RawTerminal<W> {
 }
 
 /// Types which can be converted into "raw mode".
+///
+/// # Why is this type defined on writers and not readers?
+///
+/// TTYs has their state controlled by the writer, not the reader. You use the writer to clear the
+/// screen, move the cursor and so on, so naturally you use the writer to change the mode as well.
 pub trait IntoRawMode: Write + Sized {
     /// Switch to raw mode.
     ///

src/style.rs

@@ -1,4 +1,4 @@
-//! Style.
+//! Text styling management.
 
 use std::fmt;