Document i2c.h with doxygen docstring

Closes #54

Author: taisirhassan

include/i2c.h

@@ -1,3 +1,12 @@
+/**
+ * @file
+ * @brief PIC18 I2C Controller driver (master only)
+ *
+ * This module provides I2C master functionality for the PIC18F26K83 microcontroller.
+ * It supports 7-bit addressing, configurable clock frequency, and register read/write
+ * operations for common I2C devices.
+ */
+
 #ifndef ROCKETLIB_I2C_H
 #define ROCKETLIB_I2C_H
 
@@ -8,18 +17,91 @@
 #error "C++ is not supported"
 #endif
 
-/* Initialize I2C Controller
-   I2C Frequency = (100 kHz) / (2 ^ clkdiv)
-   Max frequency clkdiv = b000, 100kHz
-   Min frequency clkdiv = b111, 781.25 Hz
-*/
+/**
+ * @brief Initialize I2C Controller
+ *
+ * This function initializes the I2C1 peripheral as a master device. The I2C clock
+ * frequency is determined by the clock divider value according to the formula:
+ * I2C Frequency = (100 kHz) / (2 ^ clkdiv)
+ *
+ * @param clkdiv Clock divider value (0-7)
+ *   - clkdiv = 0: Maximum frequency = 100 kHz
+ *   - clkdiv = 7: Minimum frequency = 781.25 Hz
+ */
 void i2c_init(uint8_t clkdiv);
 
+/**
+ * @brief Write data to an I2C device
+ *
+ * This function sends a block of data to the specified I2C device address.
+ *
+ * @param address 7-bit I2C device address (0-127)
+ * @param data Pointer to the data buffer to transmit
+ * @param len Number of bytes to transmit
+ * @return bool Returns true on success, false on error (NACK, timeout, or bus collision)
+ */
 bool i2c_write_data(uint8_t address, const uint8_t *data, uint8_t len);
+
+/**
+ * @brief Read data from an I2C device
+ *
+ * This function reads a block of data from the specified I2C device address.
+ *
+ * @param address 7-bit I2C device address (0-127)
+ * @param data Pointer to the buffer to store received data
+ * @param len Number of bytes to read
+ * @return bool Returns true on success, false on error (NACK, timeout, or bus collision)
+ */
 bool i2c_read_data(uint8_t address, uint8_t *data, uint8_t len);
+
+/**
+ * @brief Write a single byte to an I2C device register
+ *
+ * This function writes an 8-bit value to a register on the specified I2C device.
+ *
+ * @param address 7-bit I2C device address (0-127)
+ * @param reg Register address to write to
+ * @param val 8-bit value to write
+ * @return bool Returns true on success, false on error (NACK, timeout, or bus collision)
+ */
 bool i2c_write_reg8(uint8_t address, uint8_t reg, uint8_t val);
+
+/**
+ * @brief Write a 16-bit value to an I2C device register
+ *
+ * This function writes a 16-bit value to a register on the specified I2C device.
+ * The value is sent in big-endian format (MSB first).
+ *
+ * @param address 7-bit I2C device address (0-127)
+ * @param reg Register address to write to
+ * @param val 16-bit value to write
+ * @return bool Returns true on success, false on error (NACK, timeout, or bus collision)
+ */
 bool i2c_write_reg16(uint8_t address, uint8_t reg, uint16_t val);
+
+/**
+ * @brief Read a single byte from an I2C device register
+ *
+ * This function reads an 8-bit value from a register on the specified I2C device.
+ *
+ * @param address 7-bit I2C device address (0-127)
+ * @param reg Register address to read from
+ * @param value Pointer to store the read value
+ * @return bool Returns true on success, false on error (NACK, timeout, or bus collision)
+ */
 bool i2c_read_reg8(uint8_t address, uint8_t reg, uint8_t *value);
+
+/**
+ * @brief Read a 16-bit value from an I2C device register
+ *
+ * This function reads a 16-bit value from a register on the specified I2C device.
+ * The value is read in big-endian format (MSB first).
+ *
+ * @param address 7-bit I2C device address (0-127)
+ * @param reg Register address to read from
+ * @param value Pointer to store the read value
+ * @return bool Returns true on success, false on error (NACK, timeout, or bus collision)
+ */
 bool i2c_read_reg16(uint8_t address, uint8_t reg, uint16_t *value);
 
 #endif