From d01183e06c75a2a9d4ce619b63b808258cd7c100 Mon Sep 17 00:00:00 2001 From: Agathe Porte Date: Thu, 27 Feb 2020 13:44:12 +0100 Subject: lib: add examples to documented functions --- src/lib.rs | 482 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 468 insertions(+), 14 deletions(-) diff --git a/src/lib.rs b/src/lib.rs index 8f1238f..e69ade8 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -43,6 +43,20 @@ pub struct Screen { writer: T, } +// Reimplement Write trait for Screen, so that user can call the write and +// flush methods of the inner writer. +impl Write for Screen +where + T: Write, +{ + fn write(&mut self, buf: &[u8]) -> Result { + self.writer.write(buf) + } + fn flush(&mut self) -> Result<()> { + self.writer.flush() + } +} + macro_rules! write_simple_code { ($self:expr, $code:expr) => {{ $code.write_into(&mut $self.writer)?; @@ -62,6 +76,32 @@ where /// Clean the rest of the current line, from current cursor position. /// + /// # Example + /// + /// ```no_run + /// extern crate charlcd; + /// + /// use std::io::Write; + /// use charlcd::Screen; + /// + /// fn main() -> std::io::Result<()> { + /// let mut screen = Screen::default()?; + /// + /// for _ in 1..5 { + /// screen.write(b"test")?; + /// } + /// for _ in 1..8 { + /// screen.back()?; + /// } + /// screen.flush()?; // before + /// + /// screen.kill_eol()?; + /// screen.flush()?; // after + /// + /// Ok(()) + /// } + /// ``` + /// /// # Live footage (before and after) /// ![kill_eol_before](https://crates.microjoe.org/charlcd/media/docs/kill_eol_before.jpg) /// ![kill_eol](https://crates.microjoe.org/charlcd/media/docs/kill_eol.jpg) @@ -72,6 +112,29 @@ where /// Reinitialize the display to its default hardware values. /// + /// # Example + /// + /// ```no_run + /// extern crate charlcd; + /// + /// use std::io::Write; + /// use charlcd::Screen; + /// + /// fn main() -> std::io::Result<()> { + /// let mut screen = Screen::default()?; + /// + /// for _ in 1..20 { + /// screen.write(b"test")?; + /// } + /// screen.flush()?; // before + /// + /// screen.reinit()?; + /// screen.flush()?; // after + /// + /// Ok(()) + /// } + /// ``` + /// /// # Live footage (before and after) /// ![full](https://crates.microjoe.org/charlcd/media/docs/full.jpg) /// ![clear](https://crates.microjoe.org/charlcd/media/docs/clear.jpg) @@ -93,6 +156,29 @@ where /// The displayed content is not lost and kept into the screen buffer. Call /// [`Screen::display_on()`] to display back what was printed to the screen. /// + /// # Example + /// + /// ```no_run + /// extern crate charlcd; + /// + /// use std::io::Write; + /// use charlcd::Screen; + /// + /// fn main() -> std::io::Result<()> { + /// let mut screen = Screen::default()?; + /// + /// for _ in 1..20 { + /// screen.write(b"test")?; + /// } + /// screen.flush()?; // before + /// + /// screen.display_off()?; + /// screen.flush()?; // after + /// + /// Ok(()) + /// } + /// ``` + /// /// # Live footage (before and after) /// ![full](https://crates.microjoe.org/charlcd/media/docs/full.jpg) /// ![display_off](https://crates.microjoe.org/charlcd/media/docs/display_off.jpg) @@ -105,6 +191,32 @@ where /// /// The content of the screen buffer will be displayed back with no change. /// + /// # Example + /// + /// ```no_run + /// extern crate charlcd; + /// + /// use std::io::Write; + /// use charlcd::Screen; + /// + /// fn main() -> std::io::Result<()> { + /// let mut screen = Screen::default()?; + /// + /// for _ in 1..20 { + /// screen.write(b"test")?; + /// } + /// screen.flush()?; + /// + /// screen.display_off()?; + /// screen.flush()?; // before + /// + /// screen.display_on()?; + /// screen.flush()?; // after + /// + /// Ok(()) + /// } + /// ``` + /// /// # Live footage (before and after) /// ![display_off](https://crates.microjoe.org/charlcd/media/docs/display_off.jpg) /// ![full](https://crates.microjoe.org/charlcd/media/docs/full.jpg) @@ -115,6 +227,27 @@ where /// Enable the underscore cursor (independent of blinking cursor). /// + /// # Example + /// + /// ```no_run + /// extern crate charlcd; + /// + /// use std::io::Write; + /// use charlcd::Screen; + /// + /// fn main() -> std::io::Result<()> { + /// let mut screen = Screen::default()?; + /// + /// screen.write(b"test")?; + /// screen.flush()?; // before + /// + /// screen.cursor_on()?; + /// screen.flush()?; // after + /// + /// Ok(()) + /// } + /// ``` + /// /// # Live footage (before and after) /// ![test_clear](https://crates.microjoe.org/charlcd/media/docs/test_clear.jpg) /// ![cursor_on](https://crates.microjoe.org/charlcd/media/docs/cursor_on.jpg) @@ -125,6 +258,28 @@ where /// Disable the underscore cursor (independent of blinking cursor). /// + /// # Example + /// + /// ```no_run + /// extern crate charlcd; + /// + /// use std::io::Write; + /// use charlcd::Screen; + /// + /// fn main() -> std::io::Result<()> { + /// let mut screen = Screen::default()?; + /// + /// screen.write(b"test")?; + /// screen.cursor_on()?; + /// screen.flush()?; // before + /// + /// screen.cursor_off()?; + /// screen.flush()?; // after + /// + /// Ok(()) + /// } + /// ``` + /// /// # Live footage (before and after) /// ![test](https://crates.microjoe.org/charlcd/media/docs/test.jpg) /// ![cursor_off](https://crates.microjoe.org/charlcd/media/docs/blink_on.jpg) @@ -135,6 +290,27 @@ where /// Enable the blinking cursor (independent of underscore cursor). /// + /// # Example + /// + /// ```no_run + /// extern crate charlcd; + /// + /// use std::io::Write; + /// use charlcd::Screen; + /// + /// fn main() -> std::io::Result<()> { + /// let mut screen = Screen::default()?; + /// + /// screen.write(b"test")?; + /// screen.flush()?; // before + /// + /// screen.blink_on()?; + /// screen.flush()?; // after + /// + /// Ok(()) + /// } + /// ``` + /// /// # Live footage (before and after) /// ![test_clear](https://crates.microjoe.org/charlcd/media/docs/test_clear.jpg) /// ![blink_on](https://crates.microjoe.org/charlcd/media/docs/blink_on.jpg) @@ -148,6 +324,28 @@ where /// Disable the blinking cursor (independent of underscore cursor). /// + /// # Example + /// + /// ```no_run + /// extern crate charlcd; + /// + /// use std::io::Write; + /// use charlcd::Screen; + /// + /// fn main() -> std::io::Result<()> { + /// let mut screen = Screen::default()?; + /// + /// screen.write(b"test")?; + /// screen.blink_on()?; + /// screen.flush()?; // before + /// + /// screen.blink_off()?; + /// screen.flush()?; // after + /// + /// Ok(()) + /// } + /// ``` + /// /// # Live footage (before and after) /// ![test](https://crates.microjoe.org/charlcd/media/docs/test.jpg) /// ![blink_off](https://crates.microjoe.org/charlcd/media/docs/cursor_on.jpg) @@ -157,11 +355,65 @@ where } /// Enable the backlight. + /// + /// # Example + /// + /// ```no_run + /// extern crate charlcd; + /// + /// use std::io::Write; + /// use charlcd::Screen; + /// + /// fn main() -> std::io::Result<()> { + /// let mut screen = Screen::default()?; + /// + /// screen.write(b"test")?; + /// screen.backlight_off()?; + /// screen.flush()?; // before + /// + /// screen.backlight_on()?; + /// screen.flush()?; // after + /// + /// Ok(()) + /// } + /// ``` + /// + /// Note: due to poor light conditions, it is not easy to illustrate the + /// before and after steps with a photography. The *backlight* term should + /// be straightforward to understand so that a picture is not needed + /// afterall. pub fn backlight_on(&mut self) -> std::io::Result<()> { write_simple_code!(self, SpecialCode::BacklightOn) } /// Disable the backlight. + /// + /// # Example + /// + /// ```no_run + /// extern crate charlcd; + /// + /// use std::io::Write; + /// use charlcd::Screen; + /// + /// fn main() -> std::io::Result<()> { + /// let mut screen = Screen::default()?; + /// + /// screen.write(b"test")?; + /// screen.backlight_on()?; + /// screen.flush()?; // before + /// + /// screen.backlight_off()?; + /// screen.flush()?; // after + /// + /// Ok(()) + /// } + /// ``` + /// + /// Note: due to poor light conditions, it is not easy to illustrate the + /// before and after steps with a photography. The *backlight* term should + /// be straightforward to understand so that a picture is not needed + /// afterall. pub fn backlight_off(&mut self) -> std::io::Result<()> { write_simple_code!(self, SpecialCode::BacklightOff) } @@ -171,12 +423,63 @@ where /// The exact duration is specified in the driver. As of today, the default /// value is set to 4 seconds (see the `LCD_BL_TEMPO_PERIOD` define of /// the `charlcd.c` driver in your Linux tree). + /// + /// # Example + /// + /// ```no_run + /// extern crate charlcd; + /// + /// use std::io::Write; + /// use charlcd::Screen; + /// + /// fn main() -> std::io::Result<()> { + /// let mut screen = Screen::default()?; + /// + /// screen.write(b"test")?; + /// screen.backlight_off()?; + /// screen.flush()?; // before + /// + /// screen.flash_backlight()?; + /// screen.flush()?; // after + /// + /// // after some time, the screen backlight goes off by itself + /// + /// Ok(()) + /// } + /// ``` + /// + /// Note: due to poor light conditions, it is not easy to illustrate the + /// before and after steps with a photography. The *backlight* term should + /// be straightforward to understand so that a picture is not needed + /// afterall. pub fn flash_backlight(&mut self) -> std::io::Result<()> { write_simple_code!(self, SpecialCode::FlashBacklight) } /// Clear the screen and return the cursor at original (0, 0) XY position. /// + /// # Example + /// + /// ```no_run + /// extern crate charlcd; + /// + /// use std::io::Write; + /// use charlcd::Screen; + /// + /// fn main() -> std::io::Result<()> { + /// let mut screen = Screen::default()?; + /// + /// screen.reinit()?; + /// screen.write(b"test")?; + /// screen.flush()?; // before + /// + /// screen.clear()?; + /// screen.flush()?; // after + /// + /// Ok(()) + /// } + /// ``` + /// /// # Live footage (before and after) /// ![test](https://crates.microjoe.org/charlcd/media/docs/test.jpg) /// ![clear](https://crates.microjoe.org/charlcd/media/docs/clear.jpg) @@ -193,6 +496,28 @@ where /// `'\b'` escape sequence. This sequence is valid in C, but is not /// available in Rust. /// + /// # Example + /// + /// ```no_run + /// extern crate charlcd; + /// + /// use std::io::Write; + /// use charlcd::Screen; + /// + /// fn main() -> std::io::Result<()> { + /// let mut screen = Screen::default()?; + /// + /// screen.reinit()?; + /// screen.write(b"test")?; + /// screen.flush()?; // before + /// + /// screen.back()?; + /// screen.flush()?; // after + /// + /// Ok(()) + /// } + /// ``` + /// /// # Live footage (before and after) /// ![test](https://crates.microjoe.org/charlcd/media/docs/test.jpg) /// ![back](https://crates.microjoe.org/charlcd/media/docs/back.jpg) @@ -206,6 +531,28 @@ where /// Shift cursor left. /// + /// # Example + /// + /// ```no_run + /// extern crate charlcd; + /// + /// use std::io::Write; + /// use charlcd::Screen; + /// + /// fn main() -> std::io::Result<()> { + /// let mut screen = Screen::default()?; + /// + /// screen.reinit()?; + /// screen.write(b"test")?; + /// screen.flush()?; // before + /// + /// screen.shift_cursor_left()?; + /// screen.flush()?; // after + /// + /// Ok(()) + /// } + /// ``` + /// /// # Live footage (before and after) /// ![test](https://crates.microjoe.org/charlcd/media/docs/test.jpg) /// ![shift_cursor_left](https://crates.microjoe.org/charlcd/media/docs/shift_cursor_left.jpg) @@ -216,6 +563,28 @@ where /// Shift cursor right. /// + /// # Example + /// + /// ```no_run + /// extern crate charlcd; + /// + /// use std::io::Write; + /// use charlcd::Screen; + /// + /// fn main() -> std::io::Result<()> { + /// let mut screen = Screen::default()?; + /// + /// screen.reinit()?; + /// screen.write(b"test")?; + /// screen.flush()?; // before + /// + /// screen.shift_cursor_right()?; + /// screen.flush()?; // after + /// + /// Ok(()) + /// } + /// ``` + /// /// # Live footage (before and after) /// ![test](https://crates.microjoe.org/charlcd/media/docs/test.jpg) /// ![shift_cursor_right](https://crates.microjoe.org/charlcd/media/docs/shift_cursor_right.jpg) @@ -226,6 +595,30 @@ where /// Shift display left. /// + /// # Example + /// + /// ```no_run + /// extern crate charlcd; + /// + /// use std::io::Write; + /// use charlcd::Screen; + /// + /// fn main() -> std::io::Result<()> { + /// let mut screen = Screen::default()?; + /// + /// screen.reinit()?; + /// for _ in 1..5 { + /// screen.write(b"test")?; + /// } + /// screen.flush()?; // before + /// + /// screen.shift_display_left()?; + /// screen.flush()?; // after + /// + /// Ok(()) + /// } + /// ``` + /// /// # Live footage (before and after) /// ![shift](https://crates.microjoe.org/charlcd/media/docs/shift.jpg) /// ![shift_display_left](https://crates.microjoe.org/charlcd/media/docs/shift_display_left.jpg) @@ -238,6 +631,30 @@ where /// Shift display right. /// + /// # Example + /// + /// ```no_run + /// extern crate charlcd; + /// + /// use std::io::Write; + /// use charlcd::Screen; + /// + /// fn main() -> std::io::Result<()> { + /// let mut screen = Screen::default()?; + /// + /// screen.reinit()?; + /// for _ in 1..5 { + /// screen.write(b"test")?; + /// } + /// screen.flush()?; // before + /// + /// screen.shift_display_right()?; + /// screen.flush()?; // after + /// + /// Ok(()) + /// } + /// ``` + /// /// # Live footage (before and after) /// ![shift](https://crates.microjoe.org/charlcd/media/docs/shift.jpg) /// ![shift_display_right](https://crates.microjoe.org/charlcd/media/docs/shift_display_right.jpg) @@ -250,6 +667,30 @@ where /// Enable one line mode. /// + /// # Example + /// + /// ```no_run + /// extern crate charlcd; + /// + /// use std::io::Write; + /// use charlcd::Screen; + /// + /// fn main() -> std::io::Result<()> { + /// let mut screen = Screen::default()?; + /// + /// screen.reinit()?; + /// for _ in 1..20 { + /// screen.write(b"test")?; + /// } + /// screen.flush()?; // before + /// + /// screen.one_line()?; + /// screen.flush()?; // after + /// + /// Ok(()) + /// } + /// ``` + /// /// # Live footage (before and after) /// ![full](https://crates.microjoe.org/charlcd/media/docs/full.jpg) /// ![one_line](https://crates.microjoe.org/charlcd/media/docs/one_line.jpg) @@ -268,6 +709,31 @@ where /// Enable two lines mode. /// + /// # Example + /// + /// ```no_run + /// extern crate charlcd; + /// + /// use std::io::Write; + /// use charlcd::Screen; + /// + /// fn main() -> std::io::Result<()> { + /// let mut screen = Screen::default()?; + /// + /// screen.reinit()?; + /// for _ in 1..20 { + /// screen.write(b"test")?; + /// } + /// screen.one_line()?; + /// screen.flush()?; // before + /// + /// screen.two_lines()?; + /// screen.flush()?; // after + /// + /// Ok(()) + /// } + /// ``` + /// /// # Live footage (before and after) /// ![one_line](https://crates.microjoe.org/charlcd/media/docs/one_line.jpg) /// ![two_lines](https://crates.microjoe.org/charlcd/media/docs/two_lines.jpg) @@ -320,20 +786,6 @@ where } } -// Reimplement Write trait for Screen, so that user can call the write and -// flush methods of the inner writer. -impl Write for Screen -where - T: Write, -{ - fn write(&mut self, buf: &[u8]) -> Result { - self.writer.write(buf) - } - fn flush(&mut self) -> Result<()> { - self.writer.flush() - } -} - type FileScreen = Screen>; const DEFAULT_SCREEN_DEV_PATH: &str = "/dev/lcd"; @@ -359,6 +811,7 @@ impl FileScreen { /// ```no_run /// extern crate charlcd; /// + /// use std::io::Write; /// use charlcd::Screen; /// /// fn main() -> std::io::Result<()> { @@ -394,6 +847,7 @@ impl FileScreen { /// ```no_run /// extern crate charlcd; /// + /// use std::io::Write; /// use charlcd::Screen; /// /// fn main() -> std::io::Result<()> { -- cgit v1.2.3