doxdoxdox

Adafruit_BusIO_Register.cpp

@@ -1,5 +1,13 @@
 #include <Adafruit_BusIO_Register.h>
 
+/*!
+ *    @brief  Create a register we access over an I2C Device (which defines the bus and address)
+ *    @param  i2cdevice The I2CDevice to use for underlying I2C access
+ *    @param  reg_addr The address pointer value for the I2C/SMBus register, can be 8 or 16 bits
+ *    @param  width    The width of the register data itself, defaults to 1 byte
+ *    @param  bitorder The bit order of the register (used when width is > 1), defaults to LSBFIRST
+ *    @param  address_width The width of the register address itself, defaults to 1 byte
+ */
 Adafruit_BusIO_Register::Adafruit_BusIO_Register(Adafruit_I2CDevice *i2cdevice, uint16_t reg_addr, 
 						 uint8_t width, uint8_t bitorder, uint8_t address_width) {
   _i2cdevice = i2cdevice;
@@ -10,6 +18,15 @@ Adafruit_BusIO_Register::Adafruit_BusIO_Register(Adafruit_I2CDevice *i2cdevice,
   _width = width;
 }
 
+/*!
+ *    @brief  Create a register we access over an SPI Device (which defines the bus and CS pin)
+ *    @param  spidevice The SPIDevice to use for underlying I2C access
+ *    @param  reg_addr The address pointer value for the I2C/SMBus register, can be 8 or 16 bits
+ *    @param  type     The method we use to read/write data to SPI (which is not as well defined as I2C)
+ *    @param  width    The width of the register data itself, defaults to 1 byte
+ *    @param  bitorder The bit order of the register (used when width is > 1), defaults to LSBFIRST
+ *    @param  address_width The width of the register address itself, defaults to 1 byte
+ */
 Adafruit_BusIO_Register::Adafruit_BusIO_Register(Adafruit_SPIDevice *spidevice, uint16_t reg_addr, 
 						 Adafruit_BusIO_SPIRegType type,
 						 uint8_t width, uint8_t bitorder, uint8_t address_width) {
@@ -22,6 +39,17 @@ Adafruit_BusIO_Register::Adafruit_BusIO_Register(Adafruit_SPIDevice *spidevice,
   _width = width;
 }
 
+/*!
+ *    @brief  Create a register we access over an I2C or SPI Device. This is a handy function because we
+ *            can pass in NULL for the unused interface, allowing libraries to mass-define all the registers
+ *    @param  i2cdevice The I2CDevice to use for underlying I2C access, if NULL we use SPI
+ *    @param  spidevice The SPIDevice to use for underlying I2C access, if NULL we use I2C
+ *    @param  reg_addr The address pointer value for the I2C/SMBus register, can be 8 or 16 bits
+ *    @param  type     The method we use to read/write data to SPI (which is not as well defined as I2C)
+ *    @param  width    The width of the register data itself, defaults to 1 byte
+ *    @param  bitorder The bit order of the register (used when width is > 1), defaults to LSBFIRST
+ *    @param  address_width The width of the register address itself, defaults to 1 byte
+ */
 Adafruit_BusIO_Register::Adafruit_BusIO_Register(Adafruit_I2CDevice *i2cdevice, Adafruit_SPIDevice *spidevice, 
 						  Adafruit_BusIO_SPIRegType type, uint16_t reg_addr,
 						 uint8_t width, uint8_t bitorder, uint8_t address_width) {
@@ -35,6 +63,12 @@ Adafruit_BusIO_Register::Adafruit_BusIO_Register(Adafruit_I2CDevice *i2cdevice,
 }
 
 
+/*!
+ *    @brief  Write a buffer of data to the register location
+ *    @param  buffer Pointer to data to write
+ *    @param  len Number of bytes to write
+ *    @return True on successful write (only really useful for I2C as SPI is uncheckable)
+ */
 bool Adafruit_BusIO_Register::write(uint8_t *buffer, uint8_t len) {
 
   uint8_t addrbuffer[2] = {(uint8_t)(_address & 0xFF), (uint8_t)(_address>>8)};
@@ -51,6 +85,12 @@ bool Adafruit_BusIO_Register::write(uint8_t *buffer, uint8_t len) {
   return false;
 }
 
+/*!
+ *    @brief  Write up to 4 bytes of data to the register location
+ *    @param  value Data to write
+ *    @param  numbytes How many bytes from 'value' to write
+ *    @return True on successful write (only really useful for I2C as SPI is uncheckable)
+ */
 bool Adafruit_BusIO_Register::write(uint32_t value, uint8_t numbytes) {
   if (numbytes == 0) {
     numbytes = _width;
@@ -70,7 +110,10 @@ bool Adafruit_BusIO_Register::write(uint32_t value, uint8_t numbytes) {
   return write(_buffer, numbytes);
 }
 
-// This does not do any error checking! returns 0xFFFFFFFF on failure
+/*!
+ *    @brief  Read data from the register location. This does not do any error checking! 
+ *    @return Returns 0xFFFFFFFF on failure, value otherwise
+ */
 uint32_t Adafruit_BusIO_Register::read(void) {
   if (! read(_buffer, _width)) {
     return -1;
@@ -91,6 +134,12 @@ uint32_t Adafruit_BusIO_Register::read(void) {
 }
 
 
+/*!
+ *    @brief  Read a buffer of data from the register location
+ *    @param  buffer Pointer to data to read into
+ *    @param  len Number of bytes to read
+ *    @return True on successful write (only really useful for I2C as SPI is uncheckable)
+ */
 bool Adafruit_BusIO_Register::read(uint8_t *buffer, uint8_t len) {
   uint8_t addrbuffer[2] = {(uint8_t)(_address & 0xFF), (uint8_t)(_address>>8)};
 
@@ -106,6 +155,11 @@ bool Adafruit_BusIO_Register::read(uint8_t *buffer, uint8_t len) {
   return false;
 }
 
+/*!
+ *    @brief  Read 2 bytes of data from the register location
+ *    @param  value Pointer to uint16_t variable to read into
+ *    @return True on successful write (only really useful for I2C as SPI is uncheckable)
+ */
 bool Adafruit_BusIO_Register::read(uint16_t *value) {
   if (! read(_buffer, 2)) {
     return false;
@@ -123,6 +177,11 @@ bool Adafruit_BusIO_Register::read(uint16_t *value) {
   return true;
 }
 
+/*!
+ *    @brief  Read 1 byte of data from the register location
+ *    @param  value Pointer to uint8_t variable to read into
+ *    @return True on successful write (only really useful for I2C as SPI is uncheckable)
+ */
 bool Adafruit_BusIO_Register::read(uint8_t *value) {
   if (! read(_buffer, 1)) {
     return false;
@@ -132,29 +191,52 @@ bool Adafruit_BusIO_Register::read(uint8_t *value) {
   return true;
 }
 
+/*!
+ *    @brief  Pretty printer for this register
+ *    @param  s The Stream to print to, defaults to &Serial
+ */
 void Adafruit_BusIO_Register::print(Stream *s) {
   uint32_t val = read();
   s->print("0x"); s->print(val, HEX);
 }
 
+/*!
+ *    @brief  Pretty printer for this register
+ *    @param  s The Stream to print to, defaults to &Serial
+ */
 void Adafruit_BusIO_Register::println(Stream *s) {
   print(s);
   s->println();
 }
 
 
+/*!
+ *    @brief  Create a slice of the register that we can address without touching other bits
+ *    @param  reg The Adafruit_BusIO_Register which defines the bus/register
+ *    @param  bits The number of bits wide we are slicing
+ *    @param  shift The number of bits that our bit-slice is shifted from LSB
+ */
 Adafruit_BusIO_RegisterBits::Adafruit_BusIO_RegisterBits(Adafruit_BusIO_Register *reg, uint8_t bits, uint8_t shift) {
   _register = reg;
   _bits = bits;
   _shift = shift;
 }
 
+/*!
+ *    @brief  Read 4 bytes of data from the register
+ *    @return  data The 4 bytes to read
+ */
 uint32_t Adafruit_BusIO_RegisterBits::read(void) {
   uint32_t val = _register->read();
   val >>= _shift;
   return val & ((1 << (_bits+1)) - 1);
 }
 
+
+/*!
+ *    @brief  Write 4 bytes of data to the register
+ *    @param  data The 4 bytes to write
+ */
 void Adafruit_BusIO_RegisterBits::write(uint32_t data) {
   uint32_t val = _register->read();
 
@@ -169,3 +251,8 @@ void Adafruit_BusIO_RegisterBits::write(uint32_t data) {
   _register->write(val, _register->width());
 }
 
+/*!
+ *    @brief  The width of the register data, helpful for doing calculations
+ *    @returns The data width used when initializing the register
+ */
+uint8_t Adafruit_BusIO_Register::width(void) { return _width; }

Adafruit_BusIO_Register.h

@@ -10,6 +10,9 @@ typedef enum _Adafruit_BusIO_SPIRegType {
   ADDRBIT8_HIGH_TOREAD = 0,
 } Adafruit_BusIO_SPIRegType;
 
+/*!
+ * @brief The class which defines a device register (a location to read/write data from)
+ */
 class Adafruit_BusIO_Register {
  public:
   Adafruit_BusIO_Register(Adafruit_I2CDevice *i2cdevice, uint16_t reg_addr, 
@@ -30,12 +33,11 @@ class Adafruit_BusIO_Register {
   bool read(uint8_t *buffer, uint8_t len);
   bool read(uint8_t *value);
   bool read(uint16_t *value);
-  bool read(uint32_t *value);
   uint32_t read(void);
   bool write(uint8_t *buffer, uint8_t len);
   bool write(uint32_t value, uint8_t numbytes=0);
 
-  uint8_t width(void) { return _width; }
+  uint8_t width(void);
 
   void print(Stream *s=&Serial);
   void println(Stream *s=&Serial);
@@ -49,6 +51,10 @@ class Adafruit_BusIO_Register {
   uint8_t _buffer[4];      // we wont support anything larger than uint32 for non-buffered read
 };
 
+
+/*!
+ * @brief The class which defines a slice of bits from within a device register (a location to read/write data from)
+ */
 class Adafruit_BusIO_RegisterBits {
  public:
   Adafruit_BusIO_RegisterBits(Adafruit_BusIO_Register *reg, uint8_t bits, uint8_t shift);

Adafruit_I2CDevice.h

@@ -3,7 +3,7 @@
 #ifndef Adafruit_I2CDevice_h
 #define Adafruit_I2CDevice_h
 
-
+///< The class which defines how we will talk to this device over I2C
 class Adafruit_I2CDevice {
  public:
   Adafruit_I2CDevice(uint8_t addr, TwoWire *theWire=&Wire);

Adafruit_SPIDevice.h

@@ -10,6 +10,7 @@
   #define MSBFIRST SPI_MSBFIRST
 #endif
 
+///< The class which defines how we will talk to this device over SPI
 class Adafruit_SPIDevice {
  public:
   Adafruit_SPIDevice(int8_t cspin,