From 251b525e7e768bccfda6c8b50b21bc5713e9d0f8 Mon Sep 17 00:00:00 2001
From: crasbe <crasbe@gmail.com>
Date: Tue, 16 Apr 2024 15:30:10 +0200
Subject: [PATCH] drivers/at24cxxx: add documentation about driver usage

---
 drivers/at24cxxx/include/at24cxxx_defines.h |  7 +++-
 drivers/at24cxxx/include/at24cxxx_params.h  |  2 +-
 drivers/include/at24cxxx.h                  | 45 +++++++++++++++++++++
 3 files changed, 52 insertions(+), 2 deletions(-)

diff --git a/drivers/at24cxxx/include/at24cxxx_defines.h b/drivers/at24cxxx/include/at24cxxx_defines.h
index a567fd71f985..73179c6455a2 100644
--- a/drivers/at24cxxx/include/at24cxxx_defines.h
+++ b/drivers/at24cxxx/include/at24cxxx_defines.h
@@ -11,7 +11,12 @@
  * @{
  *
  * @file
- * @brief       Constants for AT24CXXX EEPROM devices.
+ * @brief       Constants for various I2C EEPROM devices.
+ *
+ * All the devices listed below are accessible as pseudomodules.
+ *
+ * @note Even though the library is called "AT24CXXX", the support for
+ * I2C EEPROMs is not limited to Atmel/Microchip devices.
  *
  * @author      Fabian Hüßler <fabian.huessler@ovgu.de>
  */
diff --git a/drivers/at24cxxx/include/at24cxxx_params.h b/drivers/at24cxxx/include/at24cxxx_params.h
index b9f1b029e515..e941b7e06202 100644
--- a/drivers/at24cxxx/include/at24cxxx_params.h
+++ b/drivers/at24cxxx/include/at24cxxx_params.h
@@ -11,7 +11,7 @@
  * @{
  *
  * @file
- * @brief       Default configuration for AT24CXXX
+ * @brief       Default configuration for the AT24CXXX driver
  *
  * @author      Fabian Hüßler <fabian.huessler@ovgu.de>
  */
diff --git a/drivers/include/at24cxxx.h b/drivers/include/at24cxxx.h
index 7da67d2b7ee5..2ca51d0243d6 100644
--- a/drivers/include/at24cxxx.h
+++ b/drivers/include/at24cxxx.h
@@ -11,6 +11,51 @@
  * @ingroup     drivers_misc
  * @brief       Device driver interface for the AT24CXXX EEPROM units
  *
+ * @section overview Overview
+ * Various manufacturers such as Atmel/Microchip or ST offer small I2C EEPROMs which usually
+ * come in 8-pin packages and are used for persistent data storage of settings, counters, etc.
+ * This driver adds support for these devices with direct read and write functions.
+ *
+ * The high level wrapper for RIOTs MTD interface to utilize the I2C EEPROMs as MTD storage
+ * is described in drivers_mtd_at24cxxx.
+ *
+ * A list of supported devices can be found in the at24cxxx_defines.h file.
+ *
+ * @section usage Usage
+ *
+ * The preconfigured devices in the at24cxxx_defines.h file devices are easily
+ * accessible as pseudomodules and can be added to the Makefile of your project:
+ *
+ *      USEMODULE += at24c02
+ *
+ * When using one of the pseudomodules, the configuration of the device is already
+ * predefined in the AT24CXXX_PARAMS macro and can be used for the
+ * initialization:
+ *
+ *      at24cxxx_t eeprom_dev;
+ *      at24cxxx_params_t eeprom_params = AT24CXXX_PARAMS;
+ *
+ *      at24cxxx_init(&eeprom_dev, &eeprom_params);
+ *
+ * \n
+ * For other devices that are not yet part of the library, the generic module
+ * has to be added:
+ *
+ *      USEMODULE += at24cxxx
+ *
+ * The predefined macro can not be used in this case, so the parameters of the
+ * device have to be added to the at24cxxx_params_t structure manually with
+ * the values from the corresponding datasheet:
+ *
+ *      at24cxxx_t eeprom_dev;
+ *      at24cxxx_params_t eeprom_params = {
+ *          .i2c = I2C_DEV(0), \
+ *          ...
+ *      };
+ *
+ *      at24cxxx_init(&eeprom_dev, &eeprom_params);
+ *
+ *
  * @{
  *
  * @file