improved digital compatibility docs

Author: ryankurte

src/digital/v1_compat.rs

@@ -1,7 +1,39 @@
-//! v1 compatibility wrapper
-//! this module adds reverse support for v2 digital traits
-//! v2 traits must be explicitly cast to the v1 version using `.into()`,
-//! and will panic on internal errors
+//! v1 compatibility wrappers
+//! 
+//! this module provides wrappers to support use of v2 implementations with
+//! v1 consumers. v2 traits must be explicitly cast to the v1 version using 
+//! `.into()`, and will panic on internal errors
+//! 
+//! ```
+//! extern crate embedded_hal;
+//! use embedded_hal::digital::{v1, v2, v1_compat::OldOutputPin};
+//! 
+//! struct NewOutputPinImpl {}
+//! 
+//! impl v2::OutputPin for NewOutputPinImpl {
+//!     type Error = ();
+//!     fn set_low(&mut self) -> Result<(), Self::Error> { Ok(()) }
+//!     fn set_high(&mut self) -> Result<(), Self::Error>{ Ok(()) }
+//! }
+//! 
+//! struct OldOutputPinConsumer<T: v1::OutputPin> {
+//!     _pin: T,
+//! }
+//! 
+//! impl <T>OldOutputPinConsumer<T> 
+//! where T: v1::OutputPin {
+//!     pub fn new(pin: T) -> OldOutputPinConsumer<T> {
+//!         OldOutputPinConsumer{ _pin: pin }
+//!     }
+//! }
+//! 
+//! fn main() {
+//!     let pin = NewOutputPinImpl{};
+//!     let _consumer: OldOutputPinConsumer<OldOutputPin<_>> = OldOutputPinConsumer::new(pin.into());
+//! }
+//! ```
+//! 
+
 
 #[allow(deprecated)]
 use super::v1;

src/digital/v2_compat.rs

@@ -1,5 +1,36 @@
 //! v2 compatibility shims
+//! 
 //! this module adds implicit forward support to v1 digital traits
+//! allowing v1 implementations to be directly used with v2 consumers.
+//! 
+//! ```
+//! extern crate embedded_hal;
+//! use embedded_hal::digital::{v1, v2};
+//! 
+//! struct OldOutputPinImpl { }
+//! 
+//! impl v1::OutputPin for OldOutputPinImpl {
+//!     fn set_low(&mut self) { }
+//!     fn set_high(&mut self) { }
+//! }
+//! 
+//! struct NewOutputPinConsumer<T: v2::OutputPin> {
+//!     _pin: T,
+//! }
+//! 
+//! impl <T>NewOutputPinConsumer<T> 
+//! where T: v2::OutputPin {
+//!     pub fn new(pin: T) -> NewOutputPinConsumer<T> {
+//!         NewOutputPinConsumer{ _pin: pin }
+//!     }
+//! }
+//! 
+//! fn main() {
+//!     let pin = OldOutputPinImpl{};
+//!     let _consumer = NewOutputPinConsumer::new(pin);
+//! }
+//! ```
+//! 
 
 #[allow(deprecated)]
 use super::v1;