From 6eb63d55a4fd82ac3ec24041ac7f94c01945176d Mon Sep 17 00:00:00 2001
From: Wesley Moore <wes@wezm.net>
Date: Wed, 26 Dec 2018 14:03:02 +1100
Subject: [PATCH] Document some more items and make some more public

The newly made public items are so that arbitrary commands can be sent.
---
 src/command.rs   |  7 +++++--
 src/config.rs    |  3 +++
 src/interface.rs | 11 +++++++++++
 src/lib.rs       | 38 +++++++++++++++++++++++---------------
 4 files changed, 42 insertions(+), 17 deletions(-)

diff --git a/src/command.rs b/src/command.rs
index e2922ac..155cb51 100644
--- a/src/command.rs
+++ b/src/command.rs
@@ -53,6 +53,7 @@ pub enum DeepSleepMode {
     DiscardRAM,
 }
 
+/// A command that can be issued to the controller.
 #[derive(Clone, Copy)]
 pub enum Command {
     /// Set the MUX of gate lines, scanning sequence and direction
@@ -211,7 +212,8 @@ macro_rules! pack {
 }
 
 impl Command {
-    pub(crate) fn execute<I: DisplayInterface>(&self, interface: &mut I) -> Result<(), I::Error> {
+    /// Execute the command, transmitting any associated data as well.
+    pub fn execute<I: DisplayInterface>(&self, interface: &mut I) -> Result<(), I::Error> {
         use self::Command::*;
 
         let mut buf = [0u8; 4];
@@ -304,7 +306,8 @@ impl Command {
 }
 
 impl<'buf> BufCommand<'buf> {
-    pub(crate) fn execute<I: DisplayInterface>(&self, interface: &mut I) -> Result<(), I::Error> {
+    /// Execute the command, transmitting the associated buffer as well.
+    pub fn execute<I: DisplayInterface>(&self, interface: &mut I) -> Result<(), I::Error> {
         use self::BufCommand::*;
 
         let (command, data) = match self {
diff --git a/src/config.rs b/src/config.rs
index 7ebab1f..85fb7df 100644
--- a/src/config.rs
+++ b/src/config.rs
@@ -36,6 +36,9 @@ pub struct Builder<'a> {
 #[derive(Debug)]
 pub struct BuilderError {}
 
+/// Display configuration.
+///
+/// Passed to Display::new. Use `Builder` to construct a `Config`.
 pub struct Config<'a> {
     pub(crate) dummy_line_period: Command,
     pub(crate) gate_line_width: Command,
diff --git a/src/interface.rs b/src/interface.rs
index 25e43ff..ba29acc 100644
--- a/src/interface.rs
+++ b/src/interface.rs
@@ -5,12 +5,23 @@ const RESET_DELAY_MS: u8 = 10;
 
 const MAX_SPI_SPEED_HZ: u32 = 20_000_000;
 
+/// Trait implemented by displays to provide implemenation of core functionality.
 pub trait DisplayInterface {
     type Error;
 
+    /// Send a command to the controller.
+    ///
+    /// Prefer calling `execute` on a [Commmand](../command/enum.Command.html) over calling this
+    /// directly.
     fn send_command(&mut self, command: u8) -> Result<(), Self::Error>;
+
+    /// Send data for a command.
     fn send_data(&mut self, data: &[u8]) -> Result<(), Self::Error>;
+
+    /// Reset the controller.
     fn reset<D: hal::blocking::delay::DelayMs<u8>>(&mut self, delay: &mut D);
+
+    /// Wait for the controller to indicate it is not busy.
     fn busy_wait(&self);
 }
 
diff --git a/src/lib.rs b/src/lib.rs
index 6391800..f366c05 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -13,21 +13,29 @@
 //! * A [display configuration][Config]
 //! * A [Display]
 //!
-//! The `Interface` captures the details of the hardware connection to the SSD1675 controller. This
+//! The [Interface] captures the details of the hardware connection to the SSD1675 controller. This
 //! includes an SPI device and some GPIO pins. The SSD1675 can control many different displays that
 //! vary in dimensions, rotation, and driving characteristics. The [Config] captures these details.
-//! To aid in constructing the `Config` there is a [Builder] interface. Finally when you have an
-//! interface and a Config a Display instance can be created. Optionally the Display can be
-//! promoted to a [GraphicDisplay], which allows it to use the functionality from the
-//! [embedded-graphics crate]. The plain display only provides the ability to update the display by
-//! passing black/white and red buffers.
+//! To aid in constructing the [Config] there is a [Builder] interface. Finally when you have an
+//! interface and a [Config] a [Display] instance can be created.
+//!
+//! Optionally the [Display] can be promoted to a [GraphicDisplay], which allows it to use the
+//! functionality from the [embedded-graphics crate][embedded-graphics]. The plain display only
+//! provides the ability to update the display by passing black/white and red buffers.
 //!
 //! To update the display you will typically follow this flow:
 //!
-//! * [reset]
-//! * [clear]
-//! * [update]
-//! * [sleep]
+//! 1. [reset](display/struct.Display.html#method.reset)
+//! 1. [clear](graphics/struct.GraphicDisplay.html#method.clear)
+//! 1. [update](graphics/struct.GraphicDisplay.html#method.update)
+//! 1. [sleep](display/struct.Display.html#method.deep_sleep)
+//!
+//! [Interface]: interface/struct.Interface.html
+//! [Display]: display/struct.Display.html
+//! [GraphicDisplay]: display/struct.GraphicDisplay.html
+//! [Config]: config/struct.Config.html
+//! [Builder]: config/struct.Builder.html
+//! [embedded-graphics]: https://crates.io/crates/embedded-graphics
 
 extern crate embedded_hal as hal;
 
@@ -36,11 +44,11 @@ extern crate embedded_hal as hal;
 extern crate std;
 
 mod color;
-mod command;
-mod config;
-mod display;
-mod graphics;
-mod interface;
+pub mod command;
+pub mod config;
+pub mod display;
+pub mod graphics;
+pub mod interface;
 
 pub use color::Color;
 pub use config::Builder;