From c602ea03e00188d86f97b1315d00053b413373ba Mon Sep 17 00:00:00 2001
From: ladyada <limor@ladyada.net>
Date: Wed, 8 Jan 2025 09:29:49 -0500
Subject: [PATCH] doxyclanged!

---
 Adafruit_BusIO_Register.cpp |  6 ++++++
 Adafruit_GenericDevice.cpp  | 31 +++++++++++++++++++++++++++----
 Adafruit_GenericDevice.h    |  7 ++++++-
 3 files changed, 39 insertions(+), 5 deletions(-)

diff --git a/Adafruit_BusIO_Register.cpp b/Adafruit_BusIO_Register.cpp
index 86d13a9..f3e8187 100644
--- a/Adafruit_BusIO_Register.cpp
+++ b/Adafruit_BusIO_Register.cpp
@@ -210,6 +210,12 @@ uint32_t Adafruit_BusIO_Register::read(void) {
  */
 uint32_t Adafruit_BusIO_Register::readCached(void) { return _cached; }
 
+/*!
+   @brief Read a number of bytes from a register into a buffer
+   @param buffer Buffer to read data into
+   @param len Number of bytes to read into the buffer
+   @return true on successful read, otherwise false
+*/
 bool Adafruit_BusIO_Register::read(uint8_t *buffer, uint8_t len) {
   uint8_t addrbuffer[2] = {(uint8_t)(_address & 0xFF),
                            (uint8_t)(_address >> 8)};
diff --git a/Adafruit_GenericDevice.cpp b/Adafruit_GenericDevice.cpp
index 917d96f..b0d8824 100644
--- a/Adafruit_GenericDevice.cpp
+++ b/Adafruit_GenericDevice.cpp
@@ -1,5 +1,10 @@
 #include "Adafruit_GenericDevice.h"
 
+/*!  @brief Create a Generic device with the provided read/write functions
+     @param read_func Function pointer for reading raw data
+     @param write_func Function pointer for writing raw data
+     @param readreg_func Function pointer for reading registers (optional)
+     @param writereg_func Function pointer for writing registers (optional) */
 Adafruit_GenericDevice::Adafruit_GenericDevice(
     busio_genericdevice_read_t read_func,
     busio_genericdevice_write_t write_func,
@@ -12,38 +17,56 @@ Adafruit_GenericDevice::Adafruit_GenericDevice(
   _begun = false;
 }
 
+/*! @brief Initializes the device
+    @return true if initialization was successful, otherwise false */
 bool Adafruit_GenericDevice::begin(void) {
   _begun = true;
   return true;
 }
 
+/*! @brief Write a buffer of data
+    @param buffer Pointer to buffer of data to write
+    @param len Number of bytes to write
+    @return true if write was successful, otherwise false */
 bool Adafruit_GenericDevice::write(const uint8_t *buffer, size_t len) {
   if (!_begun)
     return false;
-
   return _write_func(buffer, len);
 }
 
+/*! @brief Read data into a buffer
+    @param buffer Pointer to buffer to read data into
+    @param len Number of bytes to read
+    @return true if read was successful, otherwise false */
 bool Adafruit_GenericDevice::read(uint8_t *buffer, size_t len) {
   if (!_begun)
     return false;
-
   return _read_func(buffer, len);
 }
 
+/*! @brief Read from a register location
+    @param addr_buf Buffer containing register address
+    @param addrsiz Size of register address in bytes
+    @param buf Buffer to store read data
+    @param bufsiz Size of data to read in bytes
+    @return true if read was successful, otherwise false */
 bool Adafruit_GenericDevice::readRegister(uint8_t *addr_buf, uint8_t addrsiz,
                                           uint8_t *buf, uint16_t bufsiz) {
   if (!_begun || !_readreg_func)
     return false;
-
   return _readreg_func(addr_buf, addrsiz, buf, bufsiz);
 }
 
+/*! @brief Write to a register location
+    @param addr_buf Buffer containing register address
+    @param addrsiz Size of register address in bytes
+    @param buf Buffer containing data to write
+    @param bufsiz Size of data to write in bytes
+    @return true if write was successful, otherwise false */
 bool Adafruit_GenericDevice::writeRegister(uint8_t *addr_buf, uint8_t addrsiz,
                                            const uint8_t *buf,
                                            uint16_t bufsiz) {
   if (!_begun || !_writereg_func)
     return false;
-
   return _writereg_func(addr_buf, addrsiz, buf, bufsiz);
 }
diff --git a/Adafruit_GenericDevice.h b/Adafruit_GenericDevice.h
index 3cb8c5d..7dd032f 100644
--- a/Adafruit_GenericDevice.h
+++ b/Adafruit_GenericDevice.h
@@ -34,12 +34,17 @@ class Adafruit_GenericDevice {
                      uint16_t bufsiz);
 
 protected:
+  /*! @brief Function pointer for reading raw data from the device */
   busio_genericdevice_read_t _read_func;
+  /*! @brief Function pointer for writing raw data to the device */
   busio_genericdevice_write_t _write_func;
+  /*! @brief Function pointer for reading a 'register' from the device */
   busio_genericdevice_readreg_t _readreg_func;
+  /*! @brief Function pointer for writing a 'register' to the device */
   busio_genericdevice_writereg_t _writereg_func;
 
-  bool _begun;
+  bool _begun; ///< whether we have initialized yet (in case the function needs
+               ///< to do something)
 };
 
 #endif // ADAFRUIT_GENERICDEVICE_H