Improve code commenting

Most comments are now Doxygen styled. This makes the overall impression much nicer in editors where you can hover your mouse over a function to see the (Doxygen) comment, such as VSCode and Eclipse
MCUdude · Nov 21, 2020 · 1c3b88e · 1c3b88e
1 parent 4022000
commit 1c3b88e
Show file tree

Hide file tree

Showing 9 changed files with 374 additions and 349 deletions.
diff --git a/DSP_Parameter_generator.ps1 b/DSP_Parameter_generator.ps1
@@ -258,7 +258,11 @@ $hexContent
 
 $dspProgramData
 
-/* Run this function to load DSP firmware directly */
+/**
+ * @brief Function to load DSP firmware from the microcontroller flash memory
+ * 
+ * @param myDSP SigmaDSP object
+ */
 inline void loadProgram(SigmaDSP &myDSP)
 {
   myDSP.writeRegister(CORE_REGISTER_R0_ADDR, CORE_REGISTER_R0_SIZE, DSP_core_register_R0_data);

diff --git a/DSP_parameter_generator.sh b/DSP_parameter_generator.sh
@@ -306,7 +306,11 @@ BEGIN {
 
 END {
   printf("\n")
-  printf("/* Run this function to load DSP firmware directly */\n")
+  printf("/**")
+  printf("* @brief Function to load DSP firmware from the microcontroller flash memory")
+  printf("*")
+  printf("* @param myDSP SigmaDSP object")
+  printf("*/")
   printf("inline void loadProgram(SigmaDSP &myDSP)\n")
   printf("{\n")
   printf("  myDSP.writeRegister(CORE_REGISTER_R0_ADDR, CORE_REGISTER_R0_SIZE, DSP_core_register_R0_data);\n")

diff --git a/examples/0_Template/DSP_Parameter_generator.ps1 b/examples/0_Template/DSP_Parameter_generator.ps1
@@ -258,7 +258,11 @@ $hexContent
 
 $dspProgramData
 
-/* Run this function to load DSP firmware directly */
+/**
+ * @brief Function to load DSP firmware from the microcontroller flash memory
+ * 
+ * @param myDSP SigmaDSP object
+ */
 inline void loadProgram(SigmaDSP &myDSP)
 {
   myDSP.writeRegister(CORE_REGISTER_R0_ADDR, CORE_REGISTER_R0_SIZE, DSP_core_register_R0_data);

diff --git a/examples/0_Template/DSP_parameter_generator.sh b/examples/0_Template/DSP_parameter_generator.sh
@@ -306,7 +306,11 @@ BEGIN {
 
 END {
   printf("\n")
-  printf("/* Run this function to load DSP firmware directly */\n")
+  printf("/**")
+  printf("* @brief Function to load DSP firmware from the microcontroller flash memory")
+  printf("*")
+  printf("* @param myDSP SigmaDSP object")
+  printf("*/")
   printf("inline void loadProgram(SigmaDSP &myDSP)\n")
   printf("{\n")
   printf("  myDSP.writeRegister(CORE_REGISTER_R0_ADDR, CORE_REGISTER_R0_SIZE, DSP_core_register_R0_data);\n")

diff --git a/src/DSPEEPROM.cpp b/src/DSPEEPROM.cpp
@@ -1,15 +1,13 @@
 #include "DSPEEPROM.h"
 
-
-/***************************************
-Function: DSPEEPROM()
-Purpose:  The constructor creates the object
-Inputs:   TwoWire &WireObject; Reference to Wire object
-          uint8_t i2cAddress;  7-bit i2c address
-          uint16_t kbitSize;   Size of EEPROM in kilobit
-          int8_t ledPin;       Pin to toggle when flashing EEPROM
-Returns:  None
-***************************************/
+/**
+ * @brief Constructs a new DSPEEPROM::DSPEEPROM object
+ * 
+ * @param WireObject TwoWire i2c object
+ * @param i2cAddress 7-bit EEPROM i2c address
+ * @param kbitSize Size of EEPROM in kilobit
+ * @param ledPin Pin to toggle when flashing EEPROM (optional parameter)
+ */
 DSPEEPROM::DSPEEPROM(TwoWire &WireObject,uint8_t i2cAddress, uint16_t kbitSize, int8_t ledPin)
   : _WireObject(WireObject), _eepromAddress(i2cAddress), _kbitSize(kbitSize), _ledPin(ledPin)
 {  
@@ -35,11 +33,9 @@ DSPEEPROM::DSPEEPROM(TwoWire &WireObject,uint8_t i2cAddress, uint16_t kbitSize,
 }
 
 
-/***************************************
-Function: begin()
-Purpose:  Starts the i2c interface
-Returns:  None
-***************************************/
+/**
+ * @brief Starts the i2c interface
+ */
 void DSPEEPROM::begin()
 {
   // If LED is present
@@ -51,30 +47,28 @@ void DSPEEPROM::begin()
 }
 
 
-
-/***************************************
-Function: ping()
-Purpose:  Sends a i2c ping message
-Inputs:   none
-Returns:  0 - success: ack received
-          2 - error: address send, nack received
-          3 - error: data send, nack received
-          4 - error: unknown i2c error
-***************************************/
+/**
+ * @brief Sends an i2c ping message
+ * 
+ * @return ping receive status;
+ *         0 - sucess: ack received;
+ *         2 - error: address send, nack received;
+ *         3 - error: data send, nack received;
+ *         4 - error: unknown i2c error
+ */
 uint8_t DSPEEPROM::ping()
 {
   _WireObject.beginTransmission(_eepromAddress);
   return _WireObject.endTransmission();
 }
 
 
-/***************************************
-Function: getFirmwareVersion()
-Purpose:  Returns the version number of the DSP firmware
-Inputs:   None
-Returns:  Firmware version. 0 indicated that no EEPROM is found,
-          255 indicates that the EEPROM is empty
-***************************************/
+/**
+ * @brief Returns the user defined version number of the DSP firmware
+ * 
+ * @return uint8_t uirmware version. 0 indicated that no EEPROM is found, 
+           255 indicates that the EEPROM is empty
+ */
 uint8_t DSPEEPROM::getFirmwareVersion()
 {  
   _WireObject.beginTransmission(_eepromAddress);
@@ -91,16 +85,15 @@ uint8_t DSPEEPROM::getFirmwareVersion()
 }
 
 
-/***************************************
-Function: writeFirmware()
-Purpose:  Writes the passed firmware array to the EEPROM and verifies
+/**
+ * @brief Writes the passed firmware array to the EEPROM and verifies
           that the content was written.
-Inputs:   uint8_t *firmware;       Array to hold the firmware to flash
-          uint16_t size;           Firmware array length (use sizeof)
-          int8_t firmwareVersion;  Version of the DSP firmware to store
-Returns:  True if writing succeeded and content was verified to be correct, 
-          false otherwise
-***************************************/
+ * 
+ * @param firmware Array to hold the firmware to flash
+ * @param size Firmware array length (use sizeof)
+ * @param firmwareVersion Version of the DSP firmware to store(between 1 and 254)
+ * @return True if writing succeeded and content was verified to be correct, false otherwise 
+ */
 uint8_t DSPEEPROM::writeFirmware(const uint8_t *firmware, uint16_t size, int8_t firmwareVersion)
 {
   // Check if EEPROM already contains the current firmware version

diff --git a/src/DSPEEPROM.h b/src/DSPEEPROM.h
@@ -21,7 +21,7 @@ class DSPEEPROM
     const uint16_t _kbitSize;         // Size of our EEPROM in kilobits
     const int8_t _ledPin;             // Pin to toggle while writing to EEPROM
 
-    uint16_t _firmwareVersionAddress; // Holds the current DSP firmware version  
+    uint16_t _firmwareVersionAddress; // Holds the current DSP firmware version
     uint8_t ledCounter = 0x00;        // Keeps track of the LED toggle speed
 };