Add comments to some examples

examples/colors.rs

@@ -17,20 +17,26 @@ use cursive::{Cursive, Printer};
 // 256 colors.
 
 fn main() {
+    // Start as usual
     let mut siv = Cursive::default();
-
-    siv.add_layer(Canvas::new(()).with_draw(draw).fixed_size((20, 10)));
-
     siv.add_global_callback('q', |s| s.quit());
 
+    // Canvas lets us easily override any method.
+    // Canvas can have states, but we don't need any here, so we use `()`.
+    siv.add_layer(Canvas::new(()).with_draw(draw).fixed_size((20, 10)));
+
     siv.run();
 }
 
+/// Method used to draw the cube.
+///
+/// This takes as input the Canvas state and a printer.
 fn draw(_: &(), p: &Printer) {
     // We use the view size to calibrate the color
     let x_max = p.size.x as u8;
     let y_max = p.size.y as u8;
 
+    // Print each cell individually
     for x in 0..x_max {
         for y in 0..y_max {
             // We'll use a different style for each cell
@@ -48,6 +54,8 @@ fn draw(_: &(), p: &Printer) {
 
 // Gradient for the front color
 fn front_color(x: u8, y: u8, x_max: u8, y_max: u8) -> Color {
+    // We return a full 24-bits RGB color, but some backends
+    // will project it to a 256-colors palette.
     Color::Rgb(
         x * (255 / x_max),
         y * (255 / y_max),
@@ -57,6 +65,7 @@ fn front_color(x: u8, y: u8, x_max: u8, y_max: u8) -> Color {
 
 // Gradient for the background color
 fn back_color(x: u8, y: u8, x_max: u8, y_max: u8) -> Color {
+    // Let's try to have a gradient in a different direction than the front color.
     Color::Rgb(
         128 + (2 * y_max + x - 2 * y) * (128 / (x_max + 2 * y_max)),
         255 - y * (255 / y_max),

examples/edit.rs

@@ -17,8 +17,13 @@ fn main() {
             .padding((1, 1, 1, 0))
             .content(
                 EditView::new()
+                    // Call `show_popup` when the user presses `Enter`
                     .on_submit(show_popup)
+                    // Give the `EditView` a name so we can refer to it later.
                     .with_id("name")
+                    // Wrap this in a `BoxView` with a fixed width.
+                    // Do this _after_ `with_id` or the name will point to the
+                    // `BoxView` instead of `EditView`!
                     .fixed_width(20),
             )
             .button("Ok", |s| {
@@ -41,10 +46,13 @@ fn main() {
 // If the name is empty, we'll show an error message instead.
 fn show_popup(s: &mut Cursive, name: &str) {
     if name.is_empty() {
+        // Try again as many times as we need!
         s.add_layer(Dialog::info("Please enter a name!"));
     } else {
         let content = format!("Hello {}!", name);
+        // Remove the initial popup
         s.pop_layer();
+        // And put a new one instead
         s.add_layer(
             Dialog::around(TextView::new(content))
                 .button("Quit", |s| s.quit()),

examples/key_codes.rs

@@ -29,6 +29,8 @@ impl KeyCodeView {
     }
 }
 
+// Let's implement the `View` trait.
+// `View` contains many methods, but only a few are required.
 impl View for KeyCodeView {
     fn draw(&self, printer: &Printer) {
         // We simply draw every event from the history.

examples/linear.rs

@@ -10,7 +10,7 @@ use cursive::Cursive;
 fn main() {
     let mut siv = Cursive::default();
 
-    // Some description text
+    // Some description text. We want it to be long, but not _too_ long.
     let text = "This is a very simple example of linear layout. Two views \
                 are present, a short title above, and this text. The text \
                 has a fixed width, and the title is centered horizontally.";
@@ -19,17 +19,16 @@ fn main() {
     siv.add_layer(
         Dialog::around(
             LinearLayout::vertical()
-            .child(TextView::new("Title").h_align(HAlign::Center))
+                .child(TextView::new("Title").h_align(HAlign::Center))
-            // Dummy views can be used for spacing
+                // Use a DummyView as spacer
-            .child(DummyView.fixed_height(1))
+                .child(DummyView.fixed_height(1))
-            // Disabling scrolling means the view cannot shrink.
+                // Disabling scrollable means the view cannot shrink.
-            // Try resizing the window, and see what happens!
+                .child(TextView::new(text).scrollable(false))
-            .child(TextView::new(text).scrollable(false))
+                // The other views will share the remaining space.
-            .child(TextView::new(text))
+                .child(TextView::new(text))
-            .child(TextView::new(text))
+                .child(TextView::new(text))
-            .child(TextView::new(text))
+                .child(TextView::new(text))
-            // Give everything a fixed width so it doesn't get too wide
+                .fixed_width(30),
-            .fixed_width(30),
         ).button("Quit", |s| s.quit())
             .h_align(HAlign::Center),
     );