Merge pull request #117 from dbrgn/improve-top-level-docs

Improve top level docs

src/eh0.rs

@@ -1,4 +1,5 @@
-//! This is a collection of types that implement the embedded-hal version 0.x traits.
+//! This is a collection of types that implement the embedded-hal version 0.x
+//! traits.
 //!
 //! ## Usage
 //!

src/eh0/digital.rs

@@ -58,9 +58,9 @@ pub type PwmDuty = u16;
 pub struct Transaction {
     /// Kind is the transaction kind (and data) expected
     kind: TransactionKind,
-    /// Err is an optional error return for a transaction.
-    /// This is in addition to kind to allow validation that the transaction kind
-    /// is correct prior to returning the error.
+    /// An optional error return value for a transaction. This is in addition
+    /// to `kind` to allow validation that the transaction kind is correct
+    /// prior to returning the error.
     err: Option<MockError>,
 }
 

src/eh0/serial.rs

@@ -125,20 +125,17 @@
 //! serial.done();
 //! ```
 
-// This module is implemented a little differently than
-// the spi and i2c modules. We'll note that, unlike the
-// spi and i2c modules which share the foundational Generic
-// transaction queue, we provide our own implementation.
-// We found that, in keeping with the established API design
-// and the unique features of the embedded_hal serial traits
-// (described in the note below), this was a necessary trade-
-// off. We welcome any other ideas that allow us to take
-// advantage of the common components.
+// This module is implemented a little differently than the spi and i2c
+// modules. We'll note that, unlike the spi and i2c modules which share the
+// foundational Generic transaction queue, we provide our own implementation.
+// We found that, in keeping with the established API design and the unique
+// features of the embedded_hal serial traits (described in the note below),
+// this was a necessary trade- off. We welcome any other ideas that allow us to
+// take advantage of the common components.
 //
-// We also generalize over a trait's `Word`, rather than requiring
-// consumers to use traits that operate on `u8`s. This does not
-// make the public API any more confusing for users, and it permits
-// maximal flexibility.
+// We also generalize over a trait's `Word`, rather than requiring consumers to
+// use traits that operate on `u8`s. This does not make the public API any more
+// confusing for users, and it permits maximal flexibility.
 
 use std::{
     collections::VecDeque,
@@ -153,12 +150,9 @@ use crate::common::DoneCallDetector;
 
 // Note that mode is private
 //
-// Although it is public in both the spi
-// and i2c modules, the variants are not
-// required to be in the public interface.
-// We chose to not supply them publicly to
-// consumers because there is no public API
-// that readily uses them.
+// Although it is public in both the spi and i2c modules, the variants are not
+// required to be in the public interface. We chose to not supply them publicly
+// to consumers because there is no public API that readily uses them.
 
 /// Serial communication mode
 #[derive(Debug, Clone)]
@@ -179,9 +173,9 @@ enum Mode<Word> {
 
 /// A serial transaction
 ///
-/// Transactions can either be reads, writes, or flushes. A
-/// collection of transactions represent the expected operations
-/// that are performed on your serial device.
+/// Transactions can either be reads, writes, or flushes. A collection of
+/// transactions represent the expected operations that are performed on your
+/// serial device.
 ///
 /// # Example
 ///
@@ -203,10 +197,9 @@ enum Mode<Word> {
 pub struct Transaction<Word> {
     /// A collection of modes
     ///
-    /// Since we need to express a blocking write in terms of
-    /// multiple writes, we aggregate all of them into this
-    /// member. Then, they are handed-off to the mock on
-    /// construction.
+    /// Since we need to express a blocking write in terms of multiple writes,
+    /// we aggregate all of them into this member. Then, they are handed-off to
+    /// the mock on construction.
     mode: Vec<Mode<Word>>,
 }
 
@@ -281,14 +274,13 @@ where
 /// Mock serial device
 ///
 /// The mock serial device can be loaded with expected transactions, then
-/// passed-on into a serial device user. If the expectations were not met
-/// in the specified order, the type causes a panic and describes what
-/// expectation wasn't met.
+/// passed-on into a serial device user. If the expectations were not met in
+/// the specified order, the type causes a panic and describes what expectation
+/// wasn't met.
 ///
-/// The type is clonable so that it may be shared with a serial
-/// device user. Under the hood, both cloned mocks will share
-/// the same state, allowing your handle to eventually call `done()`,
-/// if desired.
+/// The type is clonable so that it may be shared with a serial device user.
+/// Under the hood, both cloned mocks will share the same state, allowing your
+/// handle to eventually call `done()`, if desired.
 #[derive(Clone)]
 pub struct Mock<Word> {
     expected_modes: Arc<Mutex<VecDeque<Mode<Word>>>>,

src/eh0/timer.rs

@@ -1,8 +1,8 @@
-//! Provides a mocked [embedded_time::Clock] that can be used for host-side testing
-//! crates that use [embedded_hal::timer].
+//! Provides a mocked [embedded_time::Clock] that can be used for host-side
+//! testing crates that use [embedded_hal::timer].
 //!
-//! The provided [embedded_time::Clock] implementation is thread safe and can be freely
-//! skipped forward with nanosecond precision.
+//! The provided [embedded_time::Clock] implementation is thread safe and can
+//! be freely skipped forward with nanosecond precision.
 //!
 //! # Usage
 //!

src/eh1.rs

@@ -1,4 +1,5 @@
-//! This is a collection of types that implement the embedded-hal version 1.x traits.
+//! This is a collection of types that implement the embedded-hal version 1.x
+//! traits.
 //!
 //! ## Usage
 //!

src/eh1/digital.rs

@@ -51,9 +51,9 @@ use crate::{common::Generic, eh1::error::MockError};
 pub struct Transaction {
     /// Kind is the transaction kind (and data) expected
     kind: TransactionKind,
-    /// Err is an optional error return for a transaction.
-    /// This is in addition to kind to allow validation that the transaction kind
-    /// is correct prior to returning the error.
+    /// An optional error return value for a transaction. This is in addition
+    /// to `kind` to allow validation that the transaction kind is correct
+    /// prior to returning the error.
     err: Option<MockError>,
 }
 
@@ -86,8 +86,9 @@ impl Transaction {
     ///
     /// This is used to mock failure behaviours.
     ///
-    /// Note that this can only be used for methods which actually return a [`Result`];
-    /// trying to invoke this for others will lead to an assertion error!
+    /// Note that this can only be used for methods which actually return a
+    /// [`Result`]; trying to invoke this for others will lead to an assertion
+    /// error!
     pub fn with_error(mut self, error: MockError) -> Self {
         assert!(
             self.kind.supports_errors(),

src/eh1/i2c.rs

@@ -173,8 +173,10 @@ impl Transaction {
 
 /// Mock I2C implementation
 ///
-/// This supports the specification and evaluation of expectations to allow automated testing of I2C based drivers.
-/// Mismatches between expectations will cause runtime assertions to assist in locating the source of the fault.
+/// This supports the specification and evaluation of expectations to allow
+/// automated testing of I2C based drivers. Mismatches between expectations
+/// will cause runtime assertions to assist in locating the source of the
+/// fault.
 pub type Mock = Generic<Transaction>;
 
 impl ErrorType for Mock {

src/eh1/pwm.rs

@@ -39,9 +39,9 @@ use crate::{common::Generic, eh1::MockError};
 pub struct Transaction {
     /// Kind is the transaction kind (and data) expected
     kind: TransactionKind,
-    /// Err is an optional error return for a transaction.
-    /// This is in addition to kind to allow validation that the transaction kind
-    /// is correct prior to returning the error.
+    /// An optional error return value for a transaction. This is in addition
+    /// to `kind` to allow validation that the transaction kind is correct
+    /// prior to returning the error.
     err: Option<MockError>,
 }
 

src/eh1/serial.rs

@@ -89,20 +89,17 @@
 //! serial.done();
 //! ```
 
-// This module is implemented a little differently than
-// the spi and i2c modules. We'll note that, unlike the
-// spi and i2c modules which share the foundational Generic
-// transaction queue, we provide our own implementation.
-// We found that, in keeping with the established API design
-// and the unique features of the embedded_hal serial traits
-// (described in the note below), this was a necessary trade-
-// off. We welcome any other ideas that allow us to take
-// advantage of the common components.
+// This module is implemented a little differently than the spi and i2c
+// modules. We'll note that, unlike the spi and i2c modules which share the
+// foundational Generic transaction queue, we provide our own implementation.
+// We found that, in keeping with the established API design and the unique
+// features of the embedded_hal serial traits (described in the note below),
+// this was a necessary trade- off. We welcome any other ideas that allow us to
+// take advantage of the common components.
 //
-// We also generalize over a trait's `Word`, rather than requiring
-// consumers to use traits that operate on `u8`s. This does not
-// make the public API any more confusing for users, and it permits
-// maximal flexibility.
+// We also generalize over a trait's `Word`, rather than requiring consumers to
+// use traits that operate on `u8`s. This does not make the public API any more
+// confusing for users, and it permits maximal flexibility.
 
 use std::{
     collections::VecDeque,
@@ -118,12 +115,9 @@ use crate::common::DoneCallDetector;
 
 // Note that mode is private
 //
-// Although it is public in both the spi
-// and i2c modules, the variants are not
-// required to be in the public interface.
-// We chose to not supply them publicly to
-// consumers because there is no public API
-// that readily uses them.
+// Although it is public in both the spi and i2c modules, the variants are not
+// required to be in the public interface. We chose to not supply them publicly
+// to consumers because there is no public API that readily uses them.
 
 /// Serial communication mode
 #[derive(Debug, Clone)]
@@ -144,9 +138,9 @@ enum Mode<Word> {
 
 /// A serial transaction
 ///
-/// Transactions can either be reads, writes, or flushes. A
-/// collection of transactions represent the expected operations
-/// that are performed on your serial device.
+/// Transactions can either be reads, writes, or flushes. A collection of
+/// transactions represent the expected operations that are performed on your
+/// serial device.
 ///
 /// # Example
 ///
@@ -168,10 +162,9 @@ enum Mode<Word> {
 pub struct Transaction<Word> {
     /// A collection of modes
     ///
-    /// Since we need to express a blocking write in terms of
-    /// multiple writes, we aggregate all of them into this
-    /// member. Then, they are handed-off to the mock on
-    /// construction.
+    /// Since we need to express a blocking write in terms of multiple writes,
+    /// we aggregate all of them into this member. Then, they are handed-off to
+    /// the mock on construction.
     mode: Vec<Mode<Word>>,
 }
 
@@ -246,14 +239,13 @@ where
 /// Mock serial device
 ///
 /// The mock serial device can be loaded with expected transactions, then
-/// passed-on into a serial device user. If the expectations were not met
-/// in the specified order, the type causes a panic and describes what
-/// expectation wasn't met.
+/// passed-on into a serial device user. If the expectations were not met in
+/// the specified order, the type causes a panic and describes what expectation
+/// wasn't met.
 ///
-/// The type is clonable so that it may be shared with a serial
-/// device user. Under the hood, both cloned mocks will share
-/// the same state, allowing your handle to eventually call `done()`,
-/// if desired.
+/// The type is clonable so that it may be shared with a serial device user.
+/// Under the hood, both cloned mocks will share the same state, allowing your
+/// handle to eventually call `done()`, if desired.
 #[derive(Clone)]
 pub struct Mock<Word> {
     expected_modes: Arc<Mutex<VecDeque<Mode<Word>>>>,

src/lib.rs

@@ -1,33 +1,45 @@
 //! This is a collection of types that implement the embedded-hal traits.
 //!
-//! The implementations never access real hardware. Instead, the hardware is mocked
-//! or no-op implementations are used.
+//! The implementations never access real hardware. Instead, the hardware is
+//! mocked or no-op implementations are used.
 //!
-//! The goal of the crate is to be able to test drivers in CI without having access
-//! to hardware.
+//! The goal of the crate is to be able to test drivers in CI without having
+//! access to hardware.
 //!
 //! ## Usage
 //!
-//! See module-level docs for more information.
+//! The general approach for testing drivers using mocks:
 //!
-//! ## embedded_hal version
+//! 1. Define the expectations: A list of transactions (e.g. a read or write
+//!    operation) that you expect the driver-under-test to invoke on the mocked
+//!    hardware
+//! 2. Instantiate the mock with the expectations
+//! 3. Run the test code
+//! 4. At the end of the test code, call the `.done()` method on the mock to
+//!    ensure that all expectations were met
 //!
-//! This crate supports both version 0.x and version 1.x of embedded-hal.  By default only support
-//! for version 0.x is enabled.  To enable support for version 1.x, use the `eh1` feature.
+//! For more information, see module-level docs.
+//!
+//! **Note:** Mocks contain an `Arc` internally and can be cloned freely. This
+//! means you can clone a mock before passing it to the driver, and then call
+//! `.done()` on the second mock instance without having to reclaim the first
+//! instance from the driver.
+//!
+//! ## embedded_hal Version Support
+//!
+//! This crate supports both version 0.x and version 1.x of embedded-hal.  By
+//! default only support for version 0.x is enabled.  To enable support for
+//! version 1.x, use the `eh1` feature.
 //!
 //! ## Cargo Features
 //!
 //! There are currently the following cargo features:
 //!
-//! - `eh0`: Provide module [`eh0`] that mocks embedded-hal version 0.x (enabled by default)
+//! - `eh0`: Provide module [`eh0`] that mocks embedded-hal version 0.x
+//!   (enabled by default)
 //! - `eh1`: Provide module [`eh1`] that mocks embedded-hal version 1.x
 //! - `embedded-time`: Enable the [`eh0::timer`] module (enabled by default)
 //! - `embedded-hal-async`: Provide mocks for embedded-hal-async in [`eh1`]
-//!
-//! ## no\_std
-//!
-//! Currently this crate is not `no_std`. If you think this is important, let
-//! me know.
 #![cfg_attr(docsrs, feature(doc_cfg), feature(doc_auto_cfg))]
 #![deny(missing_docs)]