Clean up toplevel documentation

Author: kevinmehall

src/lib.rs

@@ -9,9 +9,14 @@
 //! # i2cdev
 //!
 //! The `i2cdev` crate provides a safe interface for interface
-//! with i2c devices under Linux.  The API wraps the Linux
-//! kernel interface for interacting with i2c in userspace:
-//! https://www.kernel.org/doc/Documentation/i2c/dev-interface
+//! with i2c devices under Linux.  The API wraps the [Linux
+//! kernel interface for interacting with i2c in userspace][kernel-doc].
+//!
+//! [kernel-doc]: https://www.kernel.org/doc/Documentation/i2c/dev-interface
+//!
+//! ## Examples
+//!
+//! ### Using the SMBus methods to read from a Wii Nunchuk
 //! ```rust,no_run
 //! extern crate i2cdev;
 //!
@@ -42,6 +47,7 @@
 //! }
 //! ```
 //!
+//! ### Using the `transfer` API with an individual device
 //! ```rust,no_run
 //! extern crate i2cdev;
 //!
@@ -65,6 +71,7 @@
 //! }
 //! ```
 //!
+//! ### Using `transfer` with `LinuxI2CBus`
 //! ```rust,no_run
 //! extern crate i2cdev;
 //!