Merge pull request rust-embedded#58 from eldruin/improve-docs

Improve docs

src/core.rs

@@ -15,6 +15,7 @@ use std::error::Error;
 /// in use and the address of the slave device.  The trait is based on the
 /// Linux i2cdev interface.
 pub trait I2CDevice {
+    /// Error type
     type Error: Error;
 
     /// Read data from the device to fill the provided slice
@@ -128,12 +129,14 @@ pub trait I2CDevice {
 /// Typical implementations will store state with references to the bus
 /// in use.  The trait is based on the Linux i2cdev interface.
 pub trait I2CTransfer<'a> {
+    /// I2C transfer error type
     type Error: Error;
+    /// I2C transfer message type
     type Message: I2CMessage<'a>;
 
-    // Performs multiple serially chained I2C read/write transactions.  On
-    // success the return code is the number of successfully executed
-    // transactions
+    /// Performs multiple serially chained I2C read/write transactions.  On
+    /// success the return code is the number of successfully executed
+    /// transactions
     fn transfer(&mut self, msgs: &'a mut [Self::Message]) -> Result<u32, Self::Error>;
 }
 

src/lib.rs

@@ -96,6 +96,7 @@
 
 #![crate_name = "i2cdev"]
 #![crate_type = "lib"]
+#![deny(missing_docs)]
 
 #[macro_use]
 extern crate bitflags;
@@ -107,8 +108,12 @@ extern crate nix;
 #[cfg(any(target_os = "linux", target_os = "android"))]
 mod ffi;
 
+/// Core I2C abstractions
 pub mod core;
 
+/// Linux I2C device support
 #[cfg(any(target_os = "linux", target_os = "android"))]
 pub mod linux;
+
+/// Mock I2C device
 pub mod mock;

src/linux.rs

@@ -21,18 +21,23 @@ use std::path::Path;
 // Expose these core structs from this module
 pub use core::I2CMessage;
 
+/// Concrete linux I2C device
 pub struct LinuxI2CDevice {
     devfile: File,
     slave_address: u16,
 }
 
+/// Linux I2C bus
 pub struct LinuxI2CBus {
     devfile: File,
 }
 
+/// Linux I2C errors
 #[derive(Debug)]
 pub enum LinuxI2CError {
+    /// OS error
     Nix(nix::Error),
+    /// Input/output error
     Io(io::Error),
 }
 
@@ -322,6 +327,7 @@ impl<'a> I2CMessage<'a> for LinuxI2CMessage<'a> {
 }
 
 impl<'a> LinuxI2CMessage<'a> {
+    /// Set the target device address for the message
     pub fn with_address(self, slave_address: u16) -> Self {
         Self {
             addr: slave_address,
@@ -331,6 +337,7 @@ impl<'a> LinuxI2CMessage<'a> {
         }
     }
 
+    /// Set optional message flags
     pub fn with_flags(self, flags: I2CMessageFlags) -> Self {
         Self {
             addr: self.addr,

src/mock.rs

@@ -8,8 +8,10 @@
 use core::{I2CDevice, I2CMessage, I2CTransfer};
 use std::io;
 
+/// I2C mock result type
 pub type I2CResult<T> = io::Result<T>;
 
+/// Mock I2C device register map
 pub struct I2CRegisterMap {
     registers: [u8; 0xFF],
     offset: usize,
@@ -22,13 +24,15 @@ impl Default for I2CRegisterMap {
 }
 
 impl I2CRegisterMap {
+    /// Create new mock I2C register map
     pub fn new() -> I2CRegisterMap {
         I2CRegisterMap {
             registers: [0x00; 0xFF],
             offset: 0,
         }
     }
 
+    /// Set several registers starting at the given offset
     pub fn write_regs(&mut self, offset: usize, data: &[u8]) {
         println!("WRITE | 0x{:X} : {:?}", offset, data);
         self.registers[offset..(data.len() + offset)].clone_from_slice(&data);
@@ -56,12 +60,15 @@ impl I2CRegisterMap {
     }
 }
 
+/// Mock I2C device exposing a register map
 #[derive(Default)]
 pub struct MockI2CDevice {
+    /// I2C register map
     pub regmap: I2CRegisterMap,
 }
 
 impl MockI2CDevice {
+    /// Create a new mock I2C device
     pub fn new() -> MockI2CDevice {
         MockI2CDevice {
             regmap: I2CRegisterMap::new(),
@@ -111,6 +118,7 @@ enum MessageType<'a> {
     Read(&'a mut [u8]),
 }
 
+/// Mock I2C message
 pub struct MockI2CMessage<'a> {
     msg_type: MessageType<'a>,
 }