doc updates

src/caps/mod.rs

@@ -60,7 +60,8 @@ use std::env::var;
 use terminfo::{self, capability as cap};
 
 /// Use the `ProbeHintsBuilder` to configure an instance of
-/// the `ProbeHints` struct.
+/// the `ProbeHints` struct.  `ProbeHints` are passed to the `Capabilities`
+/// constructor to influence the effective set of terminal capabilities.
 #[derive(Debug, Default, Builder, Clone)]
 #[builder(default)]
 pub struct ProbeHints {
@@ -68,7 +69,7 @@ pub struct ProbeHints {
     term: Option<String>,
 
     /// The contents of the COLORTERM environment variable.
-    /// http://invisible-island.net/ncurses/ncurses-slang.html#env_COLORTERM
+    /// <http://invisible-island.net/ncurses/ncurses-slang.html#env_COLORTERM>
     colorterm: Option<String>,
 
     /// The contents of the TERM_PROGRAM environment variable
@@ -88,14 +89,14 @@ pub struct ProbeHints {
     sixel: Option<bool>,
 
     /// Configure whether iTerm2 style graphics embedding is supported
-    /// See https://www.iterm2.com/documentation-images.html
+    /// See <https://www.iterm2.com/documentation-images.html>
     iterm2_image: Option<bool>,
 
     /// Specify whether `bce`, background color erase, is supported.
-    /// http://invisible-island.net/ncurses/ncurses-slang.html#env_COLORTERM_BCE
     bce: Option<bool>,
 
     /// The contents of the COLORTERM_BCE environment variable
+    /// <http://invisible-island.net/ncurses/ncurses-slang.html#env_COLORTERM_BCE>
     colorterm_bce: Option<String>,
 
     /// A loaded terminfo database entry
@@ -120,6 +121,11 @@ pub enum ColorLevel {
     TrueColor,
 }
 
+/// `Capabilities` holds information about the capabilities of a terminal.
+/// On POSIX systems this is largely derived from an available terminfo
+/// database, but there are some newish capabilities that are not yet
+/// described by the majority of terminfo installations and thus have some
+/// additional handling in this struct.
 pub struct Capabilities {
     color_level: ColorLevel,
     hyperlinks: bool,
@@ -145,8 +151,7 @@ impl Capabilities {
         Self::new_with_hints(hints.build().map_err(|e| err_msg(e))?)
     }
 
-    /// Given some hints and a writable handle to the terminal output stream,
+    /// Build a `Capabilities` object based on the provided `ProbeHints` object.
-    /// compute the available terminal capabilities.
     pub fn new_with_hints(hints: ProbeHints) -> Result<Self, Error> {
         let color_level = hints.color_level.unwrap_or_else(|| {
             // If set, COLORTERM overrides any other source of information
@@ -253,19 +258,19 @@ impl Capabilities {
     }
 
     /// Does the terminal support hyperlinks?
-    /// See https://gist.github.com/egmontkob/eb114294efbcd5adb1944c9f3cb5feda
+    /// See <https://gist.github.com/egmontkob/eb114294efbcd5adb1944c9f3cb5feda>
     pub fn hyperlinks(&self) -> bool {
         self.hyperlinks
     }
 
     /// Does the terminal support the iTerm2 image protocol?
-    /// See https://www.iterm2.com/documentation-images.html
+    /// See <https://www.iterm2.com/documentation-images.html>
     pub fn iterm2_image(&self) -> bool {
         self.iterm2_image
     }
 
     /// Is `bce`, background color erase supported?
-    /// http://invisible-island.net/ncurses/ncurses-slang.html#env_COLORTERM_BCE
+    /// <http://invisible-island.net/ncurses/ncurses-slang.html#env_COLORTERM_BCE>
     pub fn bce(&self) -> bool {
         self.bce
     }

src/cell.rs

@@ -1,13 +1,22 @@
+//! Model a cell in the terminal display
 use color::ColorAttribute;
 pub use escape::osc::Hyperlink;
 use std::mem;
 use std::rc::Rc;
 
+/// Holds the attributes for a cell.
+/// Most style attributes are stored internally as part of a bitfield
+/// to reduce per-cell overhead.
+/// The setter methods return a mutable self reference so that they can
+/// be chained together.
 #[derive(Debug, Default, Clone, Eq, PartialEq)]
 pub struct CellAttributes {
     attributes: u16,
+    /// The foreground color
     pub foreground: ColorAttribute,
+    /// The background color
     pub background: ColorAttribute,
+    /// The hyperlink content, if any
     pub hyperlink: Option<Rc<Hyperlink>>,
 }
 
@@ -65,6 +74,10 @@ macro_rules! bitfield {
     };
 }
 
+/// The `Intensity` of a cell describes its boldness.  Most terminals
+/// implement `Intensity::Bold` by either using a bold font or by simply
+/// using an alternative color.  Some terminals implement `Intensity::Half`
+/// as a dimmer color variant.
 #[derive(Debug, Clone, Copy, Deserialize, PartialEq, Eq)]
 #[repr(u16)]
 pub enum Intensity {
@@ -73,11 +86,15 @@ pub enum Intensity {
     Half = 2,
 }
 
+/// Specify just how underlined you want your `Cell` to be
 #[derive(Debug, Clone, Copy, Deserialize, PartialEq, Eq)]
 #[repr(u16)]
 pub enum Underline {
+    /// The cell is not underlined
     None = 0,
+    /// The cell is underlined with a single line
     Single = 1,
+    /// The cell is underlined with two lines
     Double = 2,
 }
 
@@ -90,6 +107,7 @@ impl Into<bool> for Underline {
     }
 }
 
+/// Specify whether you want to slowly or rapidly annoy your users
 #[derive(Debug, Clone, Copy, Deserialize, PartialEq, Eq)]
 #[repr(u16)]
 pub enum Blink {
@@ -116,11 +134,14 @@ impl CellAttributes {
     bitfield!(strikethrough, set_strikethrough, 8);
     bitfield!(invisible, set_invisible, 9);
 
-    /// Returns true if the attribute bits in both objects are equal
+    /// Returns true if the attribute bits in both objects are equal.
+    /// This can be used to cheaply test whether the styles of the two
+    /// cells are the same, and is used by some `Renderer` implementations.
     pub fn attribute_bits_equal(&self, other: &Self) -> bool {
         self.attributes == other.attributes
     }
 
+    /// Set the foreground color for the cell to that specified
     pub fn set_foreground<C: Into<ColorAttribute>>(&mut self, foreground: C) -> &mut Self {
         self.foreground = foreground.into();
         self
@@ -160,7 +181,7 @@ impl Cell {
     /// De-fang the input character such that it has no special meaning
     /// to a terminal.  All control and movement characters are rewritten
     /// as a space.
-    pub fn nerf_control_char(text: char) -> char {
+    pub(crate) fn nerf_control_char(text: char) -> char {
         if text < 0x20 as char || text == 0x7f as char {
             ' '
         } else {
@@ -168,6 +189,9 @@ impl Cell {
         }
     }
 
+    /// Create a new cell holding the specified character and with the
+    /// specified cell attributes.
+    /// All control and movement characters are rewritten as a space.
     pub fn new(text: char, attrs: CellAttributes) -> Self {
         Self {
             text: Self::nerf_control_char(text),
@@ -175,16 +199,20 @@ impl Cell {
         }
     }
 
+    /// Returns the textual content of the cell
     pub fn char(&self) -> char {
         self.text
     }
 
+    /// Returns the attributes of the cell
     pub fn attrs(&self) -> &CellAttributes {
         &self.attrs
     }
 }
 
-/// Models a change in the attributes of a cell in a stream of changes
+/// Models a change in the attributes of a cell in a stream of changes.
+/// Each variant specifies one of the possible attributes; the corresponding
+/// value holds the new value to be used for that attribute.
 #[derive(Debug, Clone, Eq, PartialEq)]
 pub enum AttributeChange {
     Intensity(Intensity),

src/color.rs

@@ -10,24 +10,42 @@ use std::result::Result;
 /// These correspond to the classic ANSI color indices and are
 /// used for convenience/readability in code
 pub enum AnsiColor {
+    /// "Dark" black
     Black = 0,
+    /// Dark red
     Maroon,
+    /// Dark green
     Green,
+    /// "Dark" yellow
     Olive,
+    /// Dark blue
     Navy,
+    /// Dark purple
     Purple,
+    /// "Dark" cyan
     Teal,
+    /// "Dark" white
     Silver,
+    /// "Bright" black
     Grey,
+    /// Bright red
     Red,
+    /// Bright green
     Lime,
+    /// Bright yellow
     Yellow,
+    /// Bright blue
     Blue,
+    /// Bright purple
     Fuschia,
+    /// Bright Cyan/Aqua
     Aqua,
+    /// Bright white
     White,
 }
 
+/// Describes a color in the SRGB colorspace using red, green and blue
+/// components in the range 0-255.
 #[derive(Debug, Clone, Copy, Default, Eq, PartialEq, Hash)]
 pub struct RgbColor {
     pub red: u8,
@@ -45,7 +63,7 @@ impl RgbColor {
     /// Construct a color from an SVG/CSS3 color name.
     /// Returns None if the supplied name is not recognized.
     /// The list of names can be found here:
-    /// https://ogeon.github.io/docs/palette/master/palette/named/index.html
+    /// <https://ogeon.github.io/docs/palette/master/palette/named/index.html>
     pub fn from_named(name: &str) -> Option<RgbColor> {
         palette::named::from_str(&name.to_ascii_lowercase()).map(|color| {
             let color = Srgb::<u8>::from_format(color);
@@ -92,6 +110,10 @@ impl<'de> Deserialize<'de> for RgbColor {
     }
 }
 
+/// Specifies the color to be used when rendering a cell.
+/// This differs from `ColorAttribute` in that this type can only
+/// specify one of the possible color types at once, whereas the
+/// `ColorAttribute` type can specify a TrueColor value and a fallback.
 #[derive(Debug, Clone, Copy, Eq, PartialEq)]
 pub enum ColorSpec {
     Default,
@@ -118,6 +140,10 @@ impl From<RgbColor> for ColorSpec {
     }
 }
 
+/// Specifies the color to be used when rendering a cell.  This is the
+/// type used in the `CellAttributes` struct and can specify an optional
+/// TrueColor value, allowing a fallback to a more traditional palette
+/// index if TrueColor is not available.
 #[derive(Debug, Default, Clone, Copy, Eq, PartialEq)]
 pub struct ColorAttribute {
     /// Used if the terminal supports full color

src/screen.rs

@@ -19,9 +19,14 @@ pub enum Position {
     EndRelative(usize),
 }
 
+/// `Change` describes an update operation to be applied to a `Screen`.
+/// Changes to the active attributes (color, style), moving the cursor
+/// and outputting text are examples of some of the values.
 #[derive(Debug, Clone, Eq, PartialEq)]
 pub enum Change {
+    /// Change a single attribute
     Attribute(AttributeChange),
+    /// Change all possible attributes to the given set of values
     AllAttributes(CellAttributes),
     /// Add printable text.
     /// Control characters are rendered inert by transforming them
@@ -38,10 +43,8 @@ pub enum Change {
     //   ClearToStartOfLine,
     //   ClearToEndOfLine,
     //   ClearToEndOfScreen,
-    CursorPosition {
+    /// Move the cursor to the specified `Position`.
-        x: Position,
+    CursorPosition { x: Position, y: Position },
-        y: Position,
-    },
     /*   CursorVisibility(bool),
      *   ChangeScrollRegion{top: usize, bottom: usize}, */
 }
@@ -125,8 +128,34 @@ impl Line {
     }
 }
 
+/// SequenceNo indicates a logical position within a stream of changes.
+/// The sequence is only meaningful within a given `Screen` instance.
 pub type SequenceNo = usize;
 
+/// The `Screen` type represents the contents of a terminal screen.
+/// It is not directly connected to a terminal device.
+/// It consists of a buffer and a log of changes.  You can accumulate
+/// updates to the screen by adding instances of the `Change` enum
+/// that describe the updates.
+///
+/// When ready to render the `Screen` to a `Terminal`, you can use
+/// the `get_changes` method to return an optimized stream of `Change`s
+/// since the last render and then pass it to an instance of `Renderer`.
+///
+/// `Screen`s can also be composited together; this is useful when
+/// building up a UI with layers or widgets: each widget can be its
+/// own `Screen` instance and have its content maintained independently
+/// from the other widgets on the screen and can then be copied into
+/// the target `Screen` buffer for rendering.
+///
+/// To support more efficient updates in the composite use case, a
+/// `draw_from_screen` method is available; the intent is to have one
+/// `Screen` be hold the data that was last rendered, and a second `Screen`
+/// of the same size that is repeatedly redrawn from the composite
+/// of the widgets.  `draw_from_screen` is used to extract the smallest
+/// difference between the updated screen and apply those changes to
+/// the render target, and then use `get_changes` to render those without
+/// repainting the world on each update.
 #[derive(Default)]
 pub struct Screen {
     width: usize,
@@ -140,6 +169,7 @@ pub struct Screen {
 }
 
 impl Screen {
+    /// Create a new Screen surface with the specified width and height.
     pub fn new(width: usize, height: usize) -> Self {
         let mut scr = Screen {
             width,
@@ -150,6 +180,15 @@ impl Screen {
         scr
     }
 
+    /// Resize the Screen surface to the specified width and height.
+    /// If the width and/or height are smaller than previously, the rows and/or
+    /// columns are truncated.  If the width and/or height are larger than
+    /// previously then an appropriate number of cells are added to the
+    /// buffer and filled with default attributes.
+    /// The resize event invalidates the change stream, discarding it and
+    /// causing a subsequent `get_changes` call to yield a full repaint.
+    /// If the cursor position would be outside the bounds of the newly resized
+    /// screen, it will be moved to be within the new bounds.
     pub fn resize(&mut self, width: usize, height: usize) {
         self.lines.resize(height, Line::with_width(width));
         for line in &mut self.lines {
@@ -327,7 +366,7 @@ impl Screen {
     }
 
     /// Returns a stream of changes suitable to update the screen
-    /// to match the model.  The input seq argument should be 0
+    /// to match the model.  The input `seq` argument should be 0
     /// on the first call, or in any situation where the screen
     /// contents may have been invalidated, otherwise it should
     /// be set to the `SequenceNo` returned by the most recent call
@@ -360,7 +399,7 @@ impl Screen {
     /// After having called `get_changes` and processed the resultant
     /// change stream, the caller can then pass the returned `SequenceNo`
     /// value to this call to prune the list of changes and free up
-    /// resources.
+    /// resources from the change log.
     pub fn flush_changes_older_than(&mut self, seq: SequenceNo) {
         let first = self.seqno.saturating_sub(self.changes.len());
         let idx = seq - first;
@@ -452,6 +491,12 @@ impl Screen {
     /// Computes the change stream required to make the region within `self`
     /// at coordinates `x`, `y` and size `width`, `height` look like the
     /// same sized region within `other` at coordinates `other_x`, `other_y`.
+    ///
+    /// `other` and `self` may be the same, causing regions within the same
+    /// `Screen` to be differenced; this is used by the `copy_region` method.
+    ///
+    /// The returned list of `Change`s can be passed to the `add_changes` method
+    /// to make the region within self match the region within other.
     /// # Panics
     /// Will panic if the regions of interest are not within the bounds of
     /// their respective `Screen`.

src/terminal.rs

@@ -17,7 +17,7 @@ use std::os::unix::io::{AsRawFd, RawFd};
 use termios::{cfmakeraw, tcsetattr, Termios, TCSANOW};
 
 /// Represents the size of the terminal screen.
-/// The number of rows and columns of character cells are returned.
+/// The number of rows and columns of character cells are expressed.
 /// Some implementations populate the size of those cells in pixels.
 // On Windows, GetConsoleFontSize() can return the size of a cell in
 // logical units and we can probably use this to populate xpixel, ypixel.
@@ -88,6 +88,7 @@ impl Handle {
     }
 }
 
+/// A unix style terminal
 pub struct UnixTerminal {
     handle: Handle,
     saved_termios: Termios,