Some docstrings for I2C module and non-pub for some apparently internal functions (#192)

* Added doc comments for I2C functions and structs

* Made some internal functions non-pub

* Apply @jameswaffles suggestions

Thanks for the good suggestions!

Co-Authored-By: James Waples <james@wapl.es>

* Minor I2C Doc updates as suggested by @jamwaffles and @therealprof

* Updated the I2C docstrings with @jamwaffles suggestions

(Let's see, when he found all nits 😉)

Co-authored-by: James Waples <james@wapl.es>

Author: jounathaen

src/i2c.rs

@@ -66,6 +66,7 @@ impl Mode {
     }
 }
 
+/// Helper trait to ensure that the correct I2C pins are used for the corresponding interface
 pub trait Pins<I2C> {
     const REMAP: bool;
 }
@@ -90,6 +91,7 @@ pub struct I2c<I2C, PINS> {
     pclk1: u32,
 }
 
+/// embedded-hal compatible blocking I2C implementation
 pub struct BlockingI2c<I2C, PINS> {
     nb: I2c<I2C, PINS>,
     start_timeout: u32,
@@ -99,6 +101,7 @@ pub struct BlockingI2c<I2C, PINS> {
 }
 
 impl<PINS> I2c<I2C1, PINS> {
+    /// Creates a generic I2C1 object on pins PB6 and PB7 or PB8 and PB9 (if remapped)
     pub fn i2c1(
         i2c: I2C1,
         pins: PINS,
@@ -116,6 +119,7 @@ impl<PINS> I2c<I2C1, PINS> {
 }
 
 impl<PINS> BlockingI2c<I2C1, PINS> {
+    /// Creates a blocking I2C1 object on pins PB6 and PB7 or PB8 and PB9 using the embedded-hal `BlockingI2c` trait.
     pub fn i2c1(
         i2c: I2C1,
         pins: PINS,
@@ -147,6 +151,7 @@ impl<PINS> BlockingI2c<I2C1, PINS> {
 }
 
 impl<PINS> I2c<I2C2, PINS> {
+    /// Creates a generic I2C2 object on pins PB10 and PB11 using the embedded-hal `BlockingI2c` trait.
     pub fn i2c2(
         i2c: I2C2,
         pins: PINS,
@@ -162,6 +167,7 @@ impl<PINS> I2c<I2C2, PINS> {
 }
 
 impl<PINS> BlockingI2c<I2C2, PINS> {
+    /// Creates a blocking I2C2 object on pins PB10 and PB1
     pub fn i2c2(
         i2c: I2C2,
         pins: PINS,
@@ -190,7 +196,8 @@ impl<PINS> BlockingI2c<I2C2, PINS> {
     }
 }
 
-pub fn blocking_i2c<I2C, PINS>(
+/// Generates a blocking I2C instance from a universal I2C object
+fn blocking_i2c<I2C, PINS>(
     i2c: I2c<I2C, PINS>,
     clocks: Clocks,
     start_timeout_us: u32,
@@ -253,12 +260,13 @@ macro_rules! busy_wait_cycles {
     }};
 }
 
+// Generate the same code for both I2Cs
 macro_rules! hal {
     ($($I2CX:ident: ($i2cX:ident),)+) => {
         $(
             impl<PINS> I2c<$I2CX, PINS> {
                 /// Configures the I2C peripheral to work in master mode
-                pub fn $i2cX(
+                fn $i2cX(
                     i2c: $I2CX,
                     pins: PINS,
                     mode: Mode,
@@ -277,6 +285,8 @@ macro_rules! hal {
                     i2c
                 }
 
+                /// Initializes I2C. Configures the `I2C_TRISE`, `I2C_CRX`, and `I2C_CCR` registers
+                /// according to the system frequency and I2C mode.
                 fn init(&mut self) {
                     let freq = self.mode.get_frequency();
                     let pclk1_mhz = (self.pclk1 / 1000000) as u16;
@@ -316,20 +326,28 @@ macro_rules! hal {
                     self.i2c.cr1.modify(|_, w| w.pe().set_bit());
                 }
 
+                /// Perform an I2C software reset
                 fn reset(&mut self) {
                     self.i2c.cr1.write(|w| w.pe().set_bit().swrst().set_bit());
                     self.i2c.cr1.reset();
                     self.init();
                 }
 
+                /// Generate START condition
                 fn send_start(&mut self) {
                     self.i2c.cr1.modify(|_, w| w.start().set_bit());
                 }
 
+                /// Check if START condition is generated. If the condition is not generated, this
+                /// method returns `WouldBlock` so the program can act accordingly
+                /// (busy wait, async, ...)
                 fn wait_after_sent_start(&mut self) -> NbResult<(), Error> {
                     wait_for_flag!(self.i2c, sb)
                 }
 
+                /// Check if STOP condition is generated. If the condition is not generated, this
+                /// method returns `WouldBlock` so the program can act accordingly
+                /// (busy wait, async, ...)
                 fn wait_for_stop(&mut self) -> NbResult<(), Error> {
                     if self.i2c.cr1.read().stop().is_no_stop() {
                         Ok(())
@@ -338,10 +356,13 @@ macro_rules! hal {
                     }
                 }
 
+                /// Sends the (7-Bit) address on the I2C bus. The 8th bit on the bus is set
+                /// depending on wether it is a read or write transfer.
                 fn send_addr(&self, addr: u8, read: bool) {
                     self.i2c.dr.write(|w| { w.dr().bits(addr << 1 | (if read {1} else {0})) });
                 }
 
+                /// Generate STOP condition
                 fn send_stop(&self) {
                     self.i2c.cr1.modify(|_, w| w.stop().set_bit());
                 }
@@ -353,7 +374,7 @@ macro_rules! hal {
             }
 
             impl<PINS> BlockingI2c<$I2CX, PINS> {
-                pub fn $i2cX(
+                fn $i2cX(
                     i2c: $I2CX,
                     pins: PINS,
                     mode: Mode,
@@ -371,7 +392,7 @@ macro_rules! hal {
 
                 fn send_start_and_wait(&mut self) -> NbResult<(), Error> {
                     // According to http://www.st.com/content/ccc/resource/technical/document/errata_sheet/f5/50/c9/46/56/db/4a/f6/CD00197763.pdf/files/CD00197763.pdf/jcr:content/translations/en.CD00197763.pdf
-                    // 2.14.4 Wrong behavior of I2C peripheral in master mode after a misplaced Stop
+                    // 2.14.4 Wrong behavior of I2C peripheral in master mode after a misplaced STOP
                     let mut retries_left = self.start_retries;
                     let mut last_ret: NbResult<(), Error> = Err(WouldBlock);
                     while retries_left > 0 {