From e63b645859cf2ff54bdc2f36da824a5c99e89ef0 Mon Sep 17 00:00:00 2001
From: ticki <ticki@users.noreply.github.com>
Date: Wed, 7 Sep 2016 11:39:32 +0200
Subject: [PATCH] Update the documentation.
---
Cargo.toml | 2 +-
README.md | 8 ++++----
examples/async.rs | 2 +-
src/async.rs | 6 ++++--
src/color.rs | 16 +++++++++++++++-
src/cursor.rs | 12 +++++++++++-
src/input.rs | 2 +-
src/raw.rs | 31 ++++++++++++++++++++++++++++++-
src/style.rs | 2 +-
9 files changed, 68 insertions(+), 13 deletions(-)
diff --git a/Cargo.toml b/Cargo.toml
index 927264f9..bd8e2039 100644
--- a/Cargo.toml
+++ b/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"
diff --git a/README.md b/README.md
index dc82a1bd..469cdabf 100644
--- a/README.md
+++ b/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,
diff --git a/examples/async.rs b/examples/async.rs
index 5227e32f..bea6ceaf 100644
--- a/examples/async.rs
+++ b/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;
diff --git a/src/async.rs b/src/async.rs
index f833f967..ed323dc7 100644
--- a/src/async.rs
+++ b/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)]
- pub recv: mpsc::Receiver<io::Result<u8>>,
+ recv: mpsc::Receiver<io::Result<u8>>,
}
impl Read for AsyncReader {
diff --git a/src/color.rs b/src/color.rs
index e4f781d9..5361f0f0 100644
--- a/src/color.rs
+++ b/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;
diff --git a/src/cursor.rs b/src/cursor.rs
index 3f0f5554..0335b205 100644
--- a/src/cursor.rs
+++ b/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);
diff --git a/src/input.rs b/src/input.rs
index d395de98..6d57cdba 100644
--- a/src/input.rs
+++ b/src/input.rs
@@ -1,4 +1,4 @@
-//! Input.
+//! User input.
use std::io::{self, Read, Write};
use std::ops;
diff --git a/src/raw.rs b/src/raw.rs
index e0d8ae98..20a07f94 100644
--- a/src/raw.rs
+++ b/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.
///
diff --git a/src/style.rs b/src/style.rs
index fba488b3..cd3eb249 100644
--- a/src/style.rs
+++ b/src/style.rs
@@ -1,4 +1,4 @@
-//! Style.
+//! Text styling management.
use std::fmt;
--
GitLab