Add and edit doc comment blocks

Author: gigapod

src/sfeTk/sfeTkIBus.h

@@ -30,9 +30,11 @@ CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 #include "sfeTkError.h"
 #include <stddef.h>
 
-// Define our error codes for the bus. Note Errors are negative, warnings/info positive
-// BUT keep the same increment on the base
-
+/**
+ * @brief Define our error codes for the bus. Note Errors are negative, warnings/info positive,
+ * but keep the same increment on the base.
+ *
+ */
 const sfeTkError_t kSTkErrBusNotInit = kSTkErrFail * (kSTkErrBaseBus + 1);
 const sfeTkError_t kSTkErrBusTimeout = kSTkErrFail * (kSTkErrBaseBus + 2);
 const sfeTkError_t kSTkErrBusNoResponse = kSTkErrFail * (kSTkErrBaseBus + 3);
@@ -42,8 +44,13 @@ const sfeTkError_t kSTkErrBusNullBuffer = kSTkErrFail * (kSTkErrBaseBus + 6);
 const sfeTkError_t kSTkErrBusUnderRead = kSTkErrBaseBus + 7;
 const sfeTkError_t kSTkErrBusNotEnabled = kSTkErrBaseBus + 8;
 
-// Define the bus interface.
-
+/**
+ * @brief Interface that defines the communication bus for the SparkFun Electronics Toolkit.
+ *
+ * The bus interface defines the basic methods for reading and writing data to a device. Specific
+ * bus implementations will extend this interface to provide the necessary functionality for the
+ * desired bus type.
+ */
 class sfeTkIBus
 {
   public:

src/sfeTk/sfeTkISPI.h

@@ -29,13 +29,28 @@ CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 
 #include "sfeTkIBus.h"
 
+/**
+ * @brief Interface that defines the SPI communication bus for the SparkFun Electronics Toolkit.
+ *
+ * The SPI bus interface extends the IBus interface and adds the ability to set and get the CS pin.
+ */
 class sfeTkISPI : public sfeTkIBus
 {
   public:
+    /*--------------------------------------------------------------------------
+        @brief Constructor for the SPI bus
+
+    */
     sfeTkISPI() : _cs{kNoCSPin}
     {
     }
 
+    /*--------------------------------------------------------------------------
+        @brief Constructor for the SPI bus
+
+        @param csPin The CS Pin for the device
+
+    */
     sfeTkISPI(uint8_t csPin) : _cs{csPin}
     {
     }
@@ -53,15 +68,18 @@ class sfeTkISPI : public sfeTkIBus
 
     /*--------------------------------------------------------------------------
         @brief getter for the cs pin
-    
+
         @retval uint8_t returns the CS pin for the device
-    
+
     */
     virtual uint8_t cs(void)
     {
         return _cs;
     }
 
+    /*--------------------------------------------------------------------------
+        @brief A constant for no CS pin
+    */
     static constexpr uint8_t kNoCSPin = 0;
 
   private:

src/sfeTk/sfeToolkit.h

@@ -26,6 +26,7 @@ CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 
 #pragma once
 
-// Include key things that are core to the toolkit
-
+/*
+    @brief Common include file for the core of the SparkFun Electronics Toolkit
+*/
 #include "sfeTkError.h"

src/sfeTkArdI2C.cpp

@@ -136,14 +136,15 @@ sfeTkError_t sfeTkArdI2C::writeRegisterWord(uint8_t devReg, uint16_t dataToWrite
     return writeRegisterRegion(devReg, (uint8_t *)&dataToWrite, sizeof(uint16_t));
 }
 
-//---------------------------------------------------------------------------------
-// writeRegisterRegionAddress()
-//
-// Writes an array of bytes of specified length to a given register on the
-//  target address
-//
-// Returns the number of bytes written, < 0 is an error
-//
+/**
+ * @brief Writes an array of bytes to a register on the target address. Supports any address size
+ *
+ * @param devReg The device's register's address - can be any size
+ * @param regLength The length of the register address
+ * @param data The data to write
+ * @param length The length of the data buffer
+ * @return sfeTkError_t Returns kSTkErrOk on success, or kSTkErrFail code
+ */
 sfeTkError_t sfeTkArdI2C::writeRegisterRegionAddress(uint8_t *devReg, size_t regLength, const uint8_t *data,
                                                      size_t length)
 {
@@ -183,12 +184,17 @@ sfeTkError_t sfeTkArdI2C::writeRegister16Region(uint16_t devReg, const uint8_t *
 }
 
 //---------------------------------------------------------------------------------
-// readRegisterRegionAnyAddress()
-//
-// Reads an array of bytes to a register on the target address
-//
-// Returns the number of bytes written, < 0 is an error
-//
+
+/**
+ * @brief Reads an array of bytes to a register on the target address. Supports any address size
+ *
+ * @param devReg The device's register's address - can be any size
+ * @param regLength The length of the register address
+ * @param data The data to buffer to read into
+ * @param numBytes The length of the data buffer
+ * @param readBytes[out] The number of bytes read
+ * @return sfeTkError_t Returns kSTkErrOk on success, or kSTkErrFail code
+ */
 sfeTkError_t sfeTkArdI2C::readRegisterRegionAnyAddress(uint8_t *devReg, size_t regLength, uint8_t *data,
                                                        size_t numBytes, size_t &readBytes)
 {