From 37485f8872618e9356503045e6492658c31cfd9b Mon Sep 17 00:00:00 2001
From: Romain Porte <microjoe@microjoe.org>
Date: Thu, 27 Feb 2020 18:26:56 +0100
Subject: first try at documenting custom_char module

---
 src/custom_char.rs | 41 +++++++++++++++++++++++++++++++++++++++++
 src/lib.rs         | 31 ++++++++++++++++++++++++++++++-
 2 files changed, 71 insertions(+), 1 deletion(-)

diff --git a/src/custom_char.rs b/src/custom_char.rs
index 47f99f5..cd43cf7 100644
--- a/src/custom_char.rs
+++ b/src/custom_char.rs
@@ -1,3 +1,40 @@
+//! Create custom characters by defining their pixels.
+//!
+//! A custom character is considered as a 8x5 pixel array.
+//!
+//! You can declare a custom character by defining an array of type `[u8; 8]`
+//! where:
+//!
+//! - each byte represents a line;
+//! - each bit in the byte represent a pixel.
+//!
+//! Only the 5 lower bits of the byte are used, because the character width is
+//! 5 pixels.
+//!
+//! # Example
+//!
+//! ```
+//! /// ▸
+//! #[cfg_attr(rustfmt, rustfmt_skip)]
+//! pub const RIGHT_ARROW: [u8; 8] = [
+//!     0b00000,
+//!     0b01000,
+//!     0b01100,
+//!     0b01110,
+//!     0b01100,
+//!     0b01000,
+//!     0b00000,
+//!     0b00000,
+//! ];
+//! ```
+//!
+//! The `#[cfg_attr(rustfmt, rustfmt_skip)]` part is required in order to
+//! avoid `rustfmt` put each item after the next one so that we cannot see the
+//! visual pixel representation of the custom character anymore.
+//!
+//! The custom character can then be put into the screen's memory by using the
+//! [`Screen::custom_char`][super::Screen::custom_char] function.
+
 /// X axis mirror of a custom LCD character
 pub const fn mirror_x(src: [u8; 8]) -> [u8; 8] {
     // const fn do not support for loops currently, hence manual unroll
@@ -21,6 +58,7 @@ pub const fn mirror_y(src: [u8; 8]) -> [u8; 8] {
     ]
 }
 
+/// ▸
 #[cfg_attr(rustfmt, rustfmt_skip)]
 pub const RIGHT_ARROW: [u8; 8] = [
     0b00000,
@@ -33,8 +71,10 @@ pub const RIGHT_ARROW: [u8; 8] = [
     0b00000,
 ];
 
+/// ◂
 pub const LEFT_ARROW: [u8; 8] = mirror_x(RIGHT_ARROW);
 
+/// ▴
 #[cfg_attr(rustfmt, rustfmt_skip)]
 pub const UP_ARROW: [u8; 8] = [
     0b00000,
@@ -47,4 +87,5 @@ pub const UP_ARROW: [u8; 8] = [
     0b00000,
 ];
 
+/// ▾
 pub const DOWN_ARROW: [u8; 8] = mirror_y(UP_ARROW);
diff --git a/src/lib.rs b/src/lib.rs
index e69ade8..23c7830 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -762,7 +762,36 @@ where
         write_simple_code!(self, SpecialCode::LargeFont)
     }
 
-    /// Custom character create
+    /// Store a custom character into the screen memory for future usage.
+    ///
+    /// See also [`custom_char`] module for a global explanation on how to
+    /// declare custom characters, as well as a list of already defined custom
+    /// characters.
+    ///
+    /// # Example
+    ///
+    /// ```no_run
+    /// extern crate charlcd;
+    ///
+    /// use std::io::Write;
+    /// use charlcd::{Screen, custom_char};
+    ///
+    /// fn main() -> std::io::Result<()> {
+    ///     let mut screen = Screen::default()?;
+    ///
+    ///     screen.reinit()?;
+    ///
+    ///     // Store the custom ▸ character in the screen memory, code 0
+    ///     screen.custom_char(0, custom_char::RIGHT_ARROW)?;
+    ///
+    ///     // Print custom character from screen memory, code 0
+    ///     screen.write(b"\x00")?;
+    ///     screen.flush()?;
+    ///
+    ///     Ok(())
+    /// }
+    /// ```
+    ///
     pub fn custom_char(&mut self, code: u8, value: [u8; 8]) -> std::io::Result<()> {
         let mut res = 0u64;
         let mut i = 0;
-- 
cgit v1.2.3