From fb5064c0eca860f9968e71a6aa58c19cb37325d7 Mon Sep 17 00:00:00 2001
From: Diego Barrios Romero <eldruin@gmail.com>
Date: Tue, 7 Jan 2020 16:19:48 +0100
Subject: [PATCH 1/2] improve docs

---
 src/core.rs  | 9 ++++++---
 src/lib.rs   | 4 ++++
 src/linux.rs | 7 +++++++
 src/mock.rs  | 8 ++++++++
 4 files changed, 25 insertions(+), 3 deletions(-)

diff --git a/src/core.rs b/src/core.rs
index b51c3a2e..10a3abbb 100644
--- a/src/core.rs
+++ b/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>;
 }
 
diff --git a/src/lib.rs b/src/lib.rs
index a4f57380..108edc56 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -107,8 +107,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;
diff --git a/src/linux.rs b/src/linux.rs
index 41ee55f1..915887ad 100644
--- a/src/linux.rs
+++ b/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,
diff --git a/src/mock.rs b/src/mock.rs
index 3ee0fad3..bc292e88 100644
--- a/src/mock.rs
+++ b/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,6 +24,7 @@ impl Default for I2CRegisterMap {
 }
 
 impl I2CRegisterMap {
+    /// Create new mock I2C register map
     pub fn new() -> I2CRegisterMap {
         I2CRegisterMap {
             registers: [0x00; 0xFF],
@@ -29,6 +32,7 @@ impl I2CRegisterMap {
         }
     }
 
+    /// 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>,
 }

From 36bb001d3935e26783bbc3e005acc985f5c61184 Mon Sep 17 00:00:00 2001
From: Diego Barrios Romero <eldruin@gmail.com>
Date: Tue, 7 Jan 2020 16:20:53 +0100
Subject: [PATCH 2/2] Deny missing docs

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

diff --git a/src/lib.rs b/src/lib.rs
index 108edc56..e845e0df 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -96,6 +96,7 @@
 
 #![crate_name = "i2cdev"]
 #![crate_type = "lib"]
+#![deny(missing_docs)]
 
 #[macro_use]
 extern crate bitflags;