More documentation

src/widgets/barchart.rs

@@ -8,16 +8,48 @@ use layout::Rect;
 use style::Color;
 use symbols::bar;
 
+/// Display multiple bars in a single widgets
+///
+/// # Examples
+///
+/// ```
+/// # extern crate tui;
+/// # use tui::widgets::{Block, border, BarChart};
+/// # use tui::style::Color;
+/// # fn main() {
+/// BarChart::default()
+///     .block(Block::default().title("BarChart").borders(border::ALL))
+///     .bar_width(3)
+///     .bar_gap(1)
+///     .bar_color(Color::Yellow)
+///     .value_color(Color::Red)
+///     .label_color(Color::White)
+///     .background_color(Color::Black)
+///     .data(&[("B0", 0), ("B1", 2), ("B2", 4), ("B3", 3)])
+///     .max(4);
+/// # }
+/// ```
 pub struct BarChart<'a> {
+    /// Block to wrap the widget in
     block: Option<Block<'a>>,
-    max: Option<u64>,
+    /// The width of each bar
     bar_width: u16,
+    /// The gap between each bar
     bar_gap: u16,
+    /// Color of the bars
     bar_color: Color,
+    /// Color of the values printed at the bottom of each bar
     value_color: Color,
+    /// Color of the labels printed under each bar
     label_color: Color,
+    /// Background color for the widget
     background_color: Color,
+    /// Slice of (label, value) pair to plot on the chart
     data: &'a [(&'a str, u64)],
+    /// Value necessary for a bar to reach the maximum height (if no value is specified,
+    /// the maximum value in the data is taken as reference)
+    max: Option<u64>,
+    /// Values to display on the bar (computed when the data is passed to the widget)
     values: Vec<String>,
 }
 

src/widgets/canvas/line.rs

@@ -1,6 +1,7 @@
 use super::Shape;
 use style::Color;
 
+/// Shape to draw a line from (x1, y1) to (x2, y2) with the given color
 pub struct Line {
     pub x1: f64,
     pub y1: f64,

src/widgets/canvas/map.rs

@@ -18,6 +18,7 @@ impl MapResolution {
     }
 }
 
+/// Shape to draw a world map with the given resolution and color
 pub struct Map {
     pub resolution: MapResolution,
     pub color: Color,

src/widgets/canvas/mod.rs

@@ -68,11 +68,12 @@ impl Grid {
     }
 }
 
+/// Holds the state of the Canvas when painting to it.
 pub struct Context<'a> {
-    x_bounds: [f64; 2],
-    y_bounds: [f64; 2],
     width: u16,
     height: u16,
+    x_bounds: [f64; 2],
+    y_bounds: [f64; 2],
     grid: Grid,
     dirty: bool,
     layers: Vec<Layer>,
@@ -80,7 +81,10 @@ pub struct Context<'a> {
 }
 
 impl<'a> Context<'a> {
-    pub fn draw<'b>(&mut self, shape: &'b Shape<'b>) {
+    /// Draw any object that may implement the Shape trait
+    pub fn draw<'b, S>(&mut self, shape: &'b S)
+        where S: Shape<'b>
+    {
         self.dirty = true;
         let left = self.x_bounds[0];
         let right = self.x_bounds[1];
@@ -96,12 +100,14 @@ impl<'a> Context<'a> {
         }
     }
 
+    /// Go one layer above in the canvas.
     pub fn layer(&mut self) {
         self.layers.push(self.grid.save());
         self.grid.reset();
         self.dirty = false;
     }
 
+    /// Print a string on the canvas at the given position
     pub fn print(&mut self, x: f64, y: f64, text: &'a str, color: Color) {
         self.labels.push(Label {
             x: x,
@@ -111,6 +117,7 @@ impl<'a> Context<'a> {
         });
     }
 
+    /// Push the last layer if necessary
     fn finish(&mut self) {
         if self.dirty {
             self.layer()
@@ -118,7 +125,8 @@ impl<'a> Context<'a> {
     }
 }
 
-///
+/// The Canvas widget may be used to draw more detailed figures using braille patterns (each
+/// cell can have a braille character in 8 different positions).
 /// # Examples
 ///
 /// ```
@@ -194,6 +202,7 @@ impl<'a, F> Canvas<'a, F>
         self
     }
 
+    /// Store the closure that will be used to draw to the Canvas
     pub fn paint(&mut self, f: F) -> &mut Canvas<'a, F> {
         self.painter = Some(f);
         self
@@ -221,6 +230,8 @@ impl<'a, F> Widget for Canvas<'a, F>
         let height = canvas_area.height as usize;
 
         if let Some(ref painter) = self.painter {
+
+            // Create a blank context that match the size of the terminal
             let mut ctx = Context {
                 x_bounds: self.x_bounds,
                 y_bounds: self.y_bounds,
@@ -231,9 +242,11 @@ impl<'a, F> Widget for Canvas<'a, F>
                 layers: Vec::new(),
                 labels: Vec::new(),
             };
+            // Paint to this context
             painter(&mut ctx);
             ctx.finish();
 
+            // Retreive painted points for each layer
             for layer in ctx.layers {
                 for (i, (ch, color)) in layer.string
                     .chars()
@@ -252,6 +265,8 @@ impl<'a, F> Widget for Canvas<'a, F>
                     }
                 }
             }
+
+            // Finally draw the labels
             for label in ctx.labels.iter().filter(|l| {
                 !(l.x < self.x_bounds[0] || l.x > self.x_bounds[1] || l.y < self.y_bounds[0] ||
                   l.y > self.y_bounds[1])

src/widgets/canvas/points.rs

@@ -3,6 +3,7 @@ use std::slice;
 use super::Shape;
 use style::Color;
 
+/// A shape to draw a group of points with the given color
 pub struct Points<'a> {
     pub coords: &'a [(f64, f64)],
     pub color: Color,

src/widgets/chart.rs

@@ -72,7 +72,9 @@ impl<'a> Axis<'a> {
 
 /// Marker to use when plotting data points
 pub enum Marker {
+    /// One point per cell
     Dot,
+    /// Up to 8 points per cell
     Braille,
 }
 
@@ -151,6 +153,37 @@ impl Default for ChartLayout {
 }
 
 /// A widget to plot one or more dataset in a cartesian coordinate system
+///
+/// # Examples
+///
+/// ```
+/// # extern crate tui;
+/// # use tui::widgets::{Block, border, Chart, Axis, Dataset, Marker};
+/// # use tui::style::Color;
+/// # fn main() {
+/// Chart::default()
+///     .block(Block::default().title("Chart"))
+///     .x_axis(Axis::default()
+///         .title("X Axis")
+///         .color(Color::Gray)
+///         .bounds([0.0, 10.0])
+///         .labels(&["0.0", "5.0", "10.0"]))
+///     .y_axis(Axis::default()
+///         .title("Y Axis")
+///         .color(Color::Gray)
+///         .bounds([0.0, 10.0])
+///         .labels(&["0.0", "5.0", "10.0"]))
+///     .datasets(&[Dataset::default()
+///                     .name("data1")
+///                     .marker(Marker::Dot)
+///                     .color(Color::Cyan)
+///                     .data(&[(0.0, 5.0), (1.0, 6.0), (1.5, 6.434)]),
+///                 Dataset::default()
+///                     .name("data2")
+///                     .marker(Marker::Braille)
+///                     .color(Color::Magenta)
+///                     .data(&[(4.0, 5.0), (5.0, 8.0), (7.66, 13.5)])]);
+/// # }
 pub struct Chart<'a> {
     /// A block to display around the widget eventually
     block: Option<Block<'a>>,

src/widgets/gauge.rs

@@ -13,7 +13,6 @@ use layout::Rect;
 /// # extern crate tui;
 /// # use tui::widgets::{Widget, Gauge, Block, border};
 /// # use tui::style::Color;
-///
 /// # fn main() {
 /// Gauge::default()
 ///     .block(Block::default().borders(border::ALL).title("Progress"))

src/widgets/mod.rs

@@ -28,11 +28,17 @@ use style::Color;
 pub mod border {
     bitflags! {
         pub flags Flags: u32 {
+            /// Show no border (default)
             const NONE  = 0b00000001,
+            /// Show the top border
             const TOP   = 0b00000010,
+            /// Show the right border
             const RIGHT = 0b00000100,
+            /// Show the bottom border
             const BOTTOM = 0b0001000,
+            /// Show the left border
             const LEFT = 0b00010000,
+            /// Show all borders
             const ALL = TOP.bits | RIGHT.bits | BOTTOM.bits | LEFT.bits,
         }
     }

src/widgets/sparkline.rs

@@ -6,11 +6,34 @@ use widgets::{Widget, Block};
 use style::Color;
 use symbols::bar;
 
+/// Widget to render a sparkline over one or more lines.
+///
+/// # Examples
+///
+/// ```
+/// # extern crate tui;
+/// # use tui::widgets::{Block, border, Sparkline};
+/// # use tui::style::Color;
+/// # fn main() {
+/// Sparkline::default()
+///     .block(Block::default().title("Sparkline").borders(border::ALL))
+///     .data(&[0, 2, 3, 4, 1, 4, 10])
+///     .max(5)
+///     .color(Color::Yellow)
+///     .background_color(Color::Red);
+/// # }
+/// ```
 pub struct Sparkline<'a> {
+    /// A block to wrap the widget in
     block: Option<Block<'a>>,
+    /// Color of the bars
     color: Color,
+    /// Background color of the widget
     background_color: Color,
+    /// A slice of the data to display
     data: &'a [u64],
+    /// The maximum value to take to compute the maximum bar height (if nothing is specified, the
+    /// widget uses the max of the dataset)
     max: Option<u64>,
 }
 

src/widgets/table.rs

@@ -8,14 +8,44 @@ use widgets::{Widget, Block};
 use layout::Rect;
 use style::Color;
 
+/// A widget to display data in formatted column
+///
+/// # Examples
+///
+/// ```
+/// # use tui::widgets::{Block, border, Table};
+/// # use tui::style::Color;
+/// # fn main() {
+/// Table::default()
+///     .block(Block::default().title("Table"))
+///     .header(&["Col1", "Col2", "Col3"])
+///     .header_color(Color::Yellow)
+///     .widths(&[5, 5, 10])
+///     .column_spacing(1)
+///     .rows(vec![["Row11", "Row12", "Row13"].as_ref(),
+///                ["Row21", "Row22", "Row23"].as_ref(),
+///                ["Row31", "Row32", "Row33"].as_ref()])
+///     .color(Color::White)
+///     .background_color(Color::Black);
+/// # }
+/// ```
 pub struct Table<'a> {
+    /// A block to wrap the widget in
     block: Option<Block<'a>>,
+    /// Header row for all columns
     header: &'a [&'a str],
+    /// Color of the text in the header
     header_color: Color,
+    /// Width of each column (if the total width is greater than the widget width some columns may
+    /// not be displayed)
     widths: &'a [u16],
-    rows: Vec<Cow<'a, [&'a str]>>,
+    /// Space between each column
-    color: Color,
     column_spacing: u16,
+    /// Data to display in each row
+    rows: Vec<Cow<'a, [&'a str]>>,
+    /// Color of the text
+    color: Color,
+    /// Background color for the widget
     background_color: Color,
 }