From a6c14dda21d2ad87c4ab88c67196260192977c27 Mon Sep 17 00:00:00 2001 From: Olle Jonsson Date: Sun, 16 Mar 2014 23:15:55 +0100 Subject: [PATCH] Documentation sprint: Terminfo --- src/libterm/lib.rs | 31 ++++++++++++++++++++----- src/libterm/terminfo/mod.rs | 7 ++++-- src/libterm/terminfo/parm.rs | 2 +- src/libterm/terminfo/parser/compiled.rs | 2 +- src/libterm/terminfo/searcher.rs | 5 ++-- 5 files changed, 35 insertions(+), 12 deletions(-) diff --git a/src/libterm/lib.rs b/src/libterm/lib.rs index 126790bd46ac6..5ccc6bfb91e1f 100644 --- a/src/libterm/lib.rs +++ b/src/libterm/lib.rs @@ -20,6 +20,7 @@ html_root_url = "http://static.rust-lang.org/doc/master")]; #[feature(macro_rules)]; +#[deny(missing_doc)]; extern crate collections; @@ -34,7 +35,9 @@ pub mod terminfo; // FIXME (#2807): Windows support. +/// Terminal color definitions pub mod color { + /// Number for a terminal color pub type Color = u16; pub static BLACK: Color = 0u16; @@ -56,8 +59,10 @@ pub mod color { pub static BRIGHT_WHITE: Color = 15u16; } +/// Terminal attributes pub mod attr { /// Terminal attributes for use with term.attr(). + /// /// Most attributes can only be turned on and must be turned off with term.reset(). /// The ones that can be turned off explicitly take a boolean value. /// Color is also represented as an attribute for convenience. @@ -103,6 +108,8 @@ fn cap_for_attr(attr: attr::Attr) -> &'static str { } } +/// A Terminal that knows how many colors it supports, with a reference to its +/// parsed TermInfo database record. pub struct Terminal { priv num_colors: u16, priv out: T, @@ -110,6 +117,14 @@ pub struct Terminal { } impl Terminal { + /// Returns a wrapped output stream (`Terminal`) as a `Result`. + /// + /// Returns `Err()` if the TERM environment variable is undefined. + /// TERM should be set to something like `xterm-color` or `screen-256color`. + /// + /// Returns `Err()` on failure to open the terminfo database correctly. + /// Also, in the event that the individual terminfo database entry can not + /// be parsed. pub fn new(out: T) -> Result, ~str> { let term = match os::getenv("TERM") { Some(t) => t, @@ -143,8 +158,8 @@ impl Terminal { /// If the color is a bright color, but the terminal only supports 8 colors, /// the corresponding normal color will be used instead. /// - /// Returns Ok(true) if the color was set, Ok(false) otherwise, and Err(e) - /// if there was an I/O error + /// Returns `Ok(true)` if the color was set, `Ok(false)` otherwise, and `Err(e)` + /// if there was an I/O error. pub fn fg(&mut self, color: color::Color) -> io::IoResult { let color = self.dim_if_necessary(color); if self.num_colors > color { @@ -166,8 +181,8 @@ impl Terminal { /// If the color is a bright color, but the terminal only supports 8 colors, /// the corresponding normal color will be used instead. /// - /// Returns Ok(true) if the color was set, Ok(false) otherwise, and Err(e) - /// if there was an I/O error + /// Returns `Ok(true)` if the color was set, `Ok(false)` otherwise, and `Err(e)` + /// if there was an I/O error. pub fn bg(&mut self, color: color::Color) -> io::IoResult { let color = self.dim_if_necessary(color); if self.num_colors > color { @@ -186,8 +201,8 @@ impl Terminal { } /// Sets the given terminal attribute, if supported. - /// Returns Ok(true) if the attribute was supported, Ok(false) otherwise, - /// and Err(e) if there was an I/O error. + /// Returns `Ok(true)` if the attribute was supported, `Ok(false)` otherwise, + /// and `Err(e)` if there was an I/O error. pub fn attr(&mut self, attr: attr::Attr) -> io::IoResult { match attr { attr::ForegroundColor(c) => self.fg(c), @@ -223,6 +238,7 @@ impl Terminal { } /// Resets all terminal attributes and color to the default. + /// Returns `Ok()`. pub fn reset(&mut self) -> io::IoResult<()> { let mut cap = self.ti.strings.find_equiv(&("sgr0")); if cap.is_none() { @@ -248,10 +264,13 @@ impl Terminal { } else { color } } + /// Returns the contained stream pub fn unwrap(self) -> T { self.out } + /// Gets an immutable reference to the stream inside pub fn get_ref<'a>(&'a self) -> &'a T { &self.out } + /// Gets a mutable reference to the stream inside pub fn get_mut<'a>(&'a mut self) -> &'a mut T { &mut self.out } } diff --git a/src/libterm/terminfo/mod.rs b/src/libterm/terminfo/mod.rs index 26a819ef2bcb8..978a8a09d0a04 100644 --- a/src/libterm/terminfo/mod.rs +++ b/src/libterm/terminfo/mod.rs @@ -8,11 +8,11 @@ // option. This file may not be copied, modified, or distributed // except according to those terms. -#[allow(missing_doc)]; +//! Terminfo database interface. use collections::HashMap; -/// A parsed terminfo entry. +/// A parsed terminfo database entry. pub struct TermInfo { /// Names for the terminal priv names: Vec<~str> , @@ -25,7 +25,10 @@ pub struct TermInfo { } pub mod searcher; + +/// TermInfo format parsing. pub mod parser { + //! ncurses-compatible compiled terminfo format parsing (term(5)) pub mod compiled; } pub mod parm; diff --git a/src/libterm/terminfo/parm.rs b/src/libterm/terminfo/parm.rs index 6975236092992..a638a07427123 100644 --- a/src/libterm/terminfo/parm.rs +++ b/src/libterm/terminfo/parm.rs @@ -38,8 +38,8 @@ enum FormatState { } /// Types of parameters a capability can use -#[deriving(Clone)] #[allow(missing_doc)] +#[deriving(Clone)] pub enum Param { String(~str), Number(int) diff --git a/src/libterm/terminfo/parser/compiled.rs b/src/libterm/terminfo/parser/compiled.rs index db615aaad620b..66d322e079f35 100644 --- a/src/libterm/terminfo/parser/compiled.rs +++ b/src/libterm/terminfo/parser/compiled.rs @@ -10,7 +10,7 @@ #[allow(non_uppercase_statics)]; -/// ncurses-compatible compiled terminfo format parsing (term(5)) +//! ncurses-compatible compiled terminfo format parsing (term(5)) use collections::HashMap; use std::io; diff --git a/src/libterm/terminfo/searcher.rs b/src/libterm/terminfo/searcher.rs index b29d7b2284e33..b5792c66a0d9c 100644 --- a/src/libterm/terminfo/searcher.rs +++ b/src/libterm/terminfo/searcher.rs @@ -8,8 +8,9 @@ // option. This file may not be copied, modified, or distributed // except according to those terms. -/// Implement ncurses-compatible database discovery -/// Does not support hashed database, only filesystem! +//! ncurses-compatible database discovery +//! +//! Does not support hashed database, only filesystem! use std::io::File; use std::os::getenv;