From e5ff811c590b9bcc85cc1ee97636d166fd968953 Mon Sep 17 00:00:00 2001
From: Diego Barrios Romero <eldruin@gmail.com>
Date: Sun, 28 Oct 2018 11:00:23 +0100
Subject: [PATCH] Add examples of creating/destroying devices

---
 src/lib.rs | 60 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 60 insertions(+)

diff --git a/src/lib.rs b/src/lib.rs
index 68e175b..0cb90c1 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -94,6 +94,66 @@
 //! - [DS3232](https://datasheets.maximintegrated.com/en/ds/DS3232.pdf)
 //! - [DS3234](https://datasheets.maximintegrated.com/en/ds/DS3234.pdf)
 //!
+//! ## Usage examples (see also examples folder)
+//!
+//! To use this driver, import this crate and an `embedded_hal` implementation,
+//! then instantiate the appropriate device.
+//! In the following 3 examples an instance of the devices DS3231, DS3232 and
+//! DS3234 will be created as an example. The rest of examples will use the
+//! DS3231 as an example, except when using features specific to another IC,
+//! for example, RAM access which is not available in the DS3231 device.
+//!
+//! ### Create a driver instance for the DS3231
+//!
+//! ```no_run
+//! extern crate linux_embedded_hal as hal;
+//! extern crate ds323x;
+//! use ds323x::Ds323x;
+//!
+//! # fn main() {
+//! let dev = hal::I2cdev::new("/dev/i2c-1").unwrap();
+//! let rtc = Ds323x::new_ds3231(dev);
+//! // do something...
+//!
+//! // get the I2C device back
+//! let dev = rtc.destroy_ds3231();
+//! # }
+//! ```
+//!
+//! ### Create a driver instance for the DS3232
+//!
+//! ```no_run
+//! extern crate linux_embedded_hal as hal;
+//! extern crate ds323x;
+//! use ds323x::Ds323x;
+//!
+//! # fn main() {
+//! let dev = hal::I2cdev::new("/dev/i2c-1").unwrap();
+//! let rtc = Ds323x::new_ds3232(dev);
+//! // do something...
+//!
+//! // get the I2C device back
+//! let dev = rtc.destroy_ds3232();
+//! # }
+//! ```
+//!
+//! ### Create a driver instance for the DS3234
+//!
+//! ```no_run
+//! extern crate linux_embedded_hal as hal;
+//! extern crate ds323x;
+//! use ds323x::Ds323x;
+//!
+//! # fn main() {
+//! let dev = hal::Spidev::open("/dev/spidev0.0").unwrap();
+//! let chip_select = hal::Pin::new(24);
+//! let rtc = Ds323x::new_ds3234(dev, chip_select);
+//! // do something...
+//!
+//! // get the SPI device and chip select pin back
+//! let (dev, chip_select) = rtc.destroy_ds3234();
+//! # }
+//! ```
 
 #![deny(unsafe_code)]
 #![deny(missing_docs)]