From a636659a9513e8bfbf4eaccd44db4373c3e817a1 Mon Sep 17 00:00:00 2001
From: anschrammh <bugreport@laposte.net>
Date: Sat, 17 Dec 2022 20:42:23 +0100
Subject: [PATCH] Commented the I2C API

---
 src/W800 SDK v1.00.08/app/drivers/i2c/i2c.h | 35 +++++++++++++++++++++
 1 file changed, 35 insertions(+)

diff --git a/src/W800 SDK v1.00.08/app/drivers/i2c/i2c.h b/src/W800 SDK v1.00.08/app/drivers/i2c/i2c.h
index dd7f5ca..4587ea8 100644
--- a/src/W800 SDK v1.00.08/app/drivers/i2c/i2c.h	
+++ b/src/W800 SDK v1.00.08/app/drivers/i2c/i2c.h	
@@ -6,12 +6,47 @@
 #include "wm_type_def.h"
 #include "wm_io.h"
 
+/**
+ * @brief Initializes the I2C peripheral by defining the SDA and SCL pin used as well as the clock frequency.
+ * 
+ * @param SDAPin the Serial DAta pin to use (check the datasheet to find an I2C capable pin)
+ * @param SCLPin the Serial CLock  pin to use (check the datasheet to find an I2C capable pin)
+ * @param frequency the clock frequency between 100000 and 400000 Hz
+ */
 void i2c_init(enum tls_io_name SDAPin, enum tls_io_name SCLPin, uint32_t frequency);
 
+/**
+ * @brief Writes the given data to the provided register of the slave device.
+ * 
+ * @param address the 7 bit address of the slave device
+ * @param reg the address of the register
+ * @param data the data to write
+ * @return true on success
+ * @return false on failure
+ */
 bool i2c_write_reg(uint8_t address, uint8_t reg, uint8_t data);
 
+/**
+ * @brief Reads multiple data in one I2C transaction from the slave device.
+ * 
+ * @param address the 7 bit address of the slave device
+ * @param reg the address of the register from where the read will start (the device should have read with autoincrement register functionality)
+ * @param data a pointer to an array of uint8_t to store the read data
+ * @param length the size in bytes of the data array
+ * @return true on success
+ * @return false on failure
+ */
 bool i2c_read(uint8_t address, uint8_t reg, uint8_t * const data, size_t length);
 
+/**
+ * @brief Reads a single data from the provided register of the slave device.
+ * 
+ * @param address the 7 bit address of the slave device
+ * @param reg the address of the register
+ * @param data a pointer to an uint8_t variable for storing the data to be read
+ * @return true on success
+ * @return false on failure
+ */
 bool i2c_read_reg(uint8_t address, uint8_t reg, uint8_t * const data);