Correct some documentation comments

avengineers · Feb 6, 2024 · faa67ae · faa67ae
1 parent fb3c803
commit faa67ae
Show file tree

Hide file tree

Showing 4 changed files with 93 additions and 87 deletions.
diff --git a/.vscode/extensions.json b/.vscode/extensions.json
@@ -14,6 +14,7 @@
         "donjayamanne.python-environment-manager",
         "felipecaputo.git-project-manager",
         "ms-vscode.powershell",
-        "waderyan.gitblame"
+        "waderyan.gitblame",
+        "sandcastle.vscode-open"
     ]
 }
diff --git a/src/light_controller/src/light_controller.c b/src/light_controller/src/light_controller.c
@@ -84,14 +84,14 @@ static void turnLightOn(void) {
 }
 
 #if CONFIG_BLINKING_RATE_AUTO_ADJUSTABLE 
-/*!
-* @rst
-*
-* .. impl:: Calculate blink period
-*    :id: SWIMPL_LC-004
-*    :implements: SWDD_LC-002
-* @endrst
-*/
+/**
+ * @rst
+ *
+ * .. impl:: Calculate blink period
+ *    :id: SWIMPL_LC-004
+ *    :implements: SWDD_LC-002
+ * @endrst
+ */
 static unsigned int calculateBlinkPeriod(percentage_t mainKnobValue) {
     // Calculate blink period based on main knob value
     unsigned int blinkPeriod = 100 - (mainKnobValue); // Adjust this formula as needed
@@ -104,10 +104,16 @@ static unsigned int calculateBlinkPeriod(percentage_t mainKnobValue) {
 #endif
 
 /**
- * @brief Controls the light behavior based on the power state.
+ * @rst
+ * .. impl:: Light Controller's main function
+ *    :id: SWIMPL_LC-006
+ *    :implements: SWDD_LC-001
+ * @endrst
+ * 
+ * @brief Controls the light state.
  *
- * Uses a state machine to determine the light's color. The light color is only updated
- * when there's a change in the power state to ensure no redundant updates.
+ * Uses a state machine to determine the light state based on several inputs,
+ * e.g., the system's power state.
  */
 void lightController(void) {
 

diff --git a/src/light_controller/test/test_light_controller.cc b/src/light_controller/test/test_light_controller.cc
@@ -47,15 +47,15 @@ std::ostream& operator<<(std::ostream& os, const RGBColor& color)
     return os;
 }
 
-/*!
-* @rst
-*
-* .. test:: light_controller.test_light_stays_off
-*    :id: TS_LC-006
-*    :tests: SWDD_LC-001, SWDD_LC-004, R_001
-*
-* @endrst
-*/
+/**
+ * @rst
+ *
+ * .. test:: light_controller.test_light_stays_off
+ *    :id: TS_LC-006
+ *    :tests: SWDD_LC-001, SWDD_LC-004, R_001
+ *
+ * @endrst
+ */
 TEST(light_controller, test_light_stays_off)
 {
     CREATE_MOCK(mymock);
@@ -69,15 +69,15 @@ TEST(light_controller, test_light_stays_off)
     }
 }
 
-/*!
-* @rst
-*
-* .. test:: light_controller.test_light_on_and_off
-*    :id: TS_LC-001
-*    :tests: SWDD_LC-001, SWDD_LC-003, SWDD_LC-004, R_002
-*
-* @endrst
-*/
+/**
+ * @rst
+ *
+ * .. test:: light_controller.test_light_on_and_off
+ *    :id: TS_LC-001
+ *    :tests: SWDD_LC-001, SWDD_LC-003, SWDD_LC-004, R_002
+ *
+ * @endrst
+ */
 TEST(light_controller, test_light_on_and_off)
 {
     CREATE_MOCK(mymock);
@@ -108,15 +108,15 @@ TEST(light_controller, test_light_on_and_off)
 }
 
 #if CONFIG_BRIGHTNESS_ADJUSTMENT
-/*!
-* @rst
-*
-* .. test:: light_controller.test_light_on_very_bright
-*    :id: TS_LC-005
-*    :tests: SWDD_LC-005
-*
-* @endrst
-*/
+/**
+ * @rst
+ *
+ * .. test:: light_controller.test_light_on_very_bright
+ *    :id: TS_LC-005
+ *    :tests: SWDD_LC-005
+ *
+ * @endrst
+ */
 TEST(light_controller, test_light_on_very_bright)
 {
     CREATE_MOCK(mymock);
@@ -136,15 +136,15 @@ TEST(light_controller, test_light_on_very_bright)
 #endif
 
 #if CONFIG_BLINKING_RATE_AUTO_ADJUSTABLE 
-/*!
-* @rst
-*
-* .. test:: light_controller.test_light_blinking
-*    :id: TS_LC-002
-*    :tests: SWDD_LC-002
-*
-* @endrst
-*/
+/**
+ * @rst
+ *
+ * .. test:: light_controller.test_light_blinking
+ *    :id: TS_LC-002
+ *    :tests: SWDD_LC-002
+ *
+ * @endrst
+ */
 TEST(light_controller, test_light_blinking)
 {
     /*!
@@ -201,20 +201,20 @@ std::ostream& operator<<(std::ostream& os, const TestParam& param)
     return os;
 }
 
-/*!
-* @rst
-*
-* .. test:: light_controller.test_correct_blink_period
-*    :id: TS_LC-004
-*    :tests: SWDD_LC-002
-*
-* @endrst
-*/
+/**
+ * @rst
+ *
+ * .. test:: light_controller.test_correct_blink_period
+ *    :id: TS_LC-004
+ *    :tests: SWDD_LC-002
+ *
+ * @endrst
+ */
 TEST(light_controller, test_correct_blink_period)
 {
-    /*!
-    * Test cases for the calculateBlinkPeriod function.
-    */
+    /**
+     * Test cases for the calculateBlinkPeriod function.
+     */
     std::vector<TestParam> test_data = {
         {"Slowest", 0, 100},
         {"Inbetween", 50, 50},
@@ -227,15 +227,15 @@ TEST(light_controller, test_correct_blink_period)
     }
 }
 
-/*!
-* @rst
-*
-* .. test:: BlinkPeriodTests/BlinkPeriodTest.CalculatesCorrectBlinkPeriod/*
-*    :id: TS_LC-003
-*    :tests: SWDD_LC-002
-*
-* @endrst
-*/
+/**
+ * @rst
+ *
+ * .. test:: BlinkPeriodTests/BlinkPeriodTest.CalculatesCorrectBlinkPeriod/*
+ *    :id: TS_LC-003
+ *    :tests: SWDD_LC-002
+ *
+ * @endrst
+ */
 TEST_P(BlinkPeriodTest, CalculatesCorrectBlinkPeriod)
 {
     // Get the parameters for this test case
@@ -256,5 +256,4 @@ INSTANTIATE_TEST_SUITE_P(
     )
 );
 
-
 #endif // CONFIG_BLINKING_RATE_AUTO_ADJUSTABLE
diff --git a/src/main_control_knob/src/main_control_knob.c b/src/main_control_knob/src/main_control_knob.c
@@ -1,26 +1,26 @@
-/** @file main_control_knob.c
-* @brief Implementation of the main control knob module.
-*
-* This file contains the implementation of the brightness of the light based on arrow up and down key presses
-*/
-
+/**
+ * @file main_control_knob.c
+ * @brief Implementation of the main control knob module.
+ *
+ * This file contains the implementation of the main knob
+ * based on arrow up and down key presses.
+ */
 
 #include "main_control_knob.h"
 #include "rte.h"
 
-/*!
-* @rst
-*
-* .. impl:: Main Control Knob
-*    :id: SWIMPL_MCK-001
-*    :implements: SWDD_MCK-001
-* @endrst
-*/
-// Function to handle knob control input.
+/**
+ * @rst
+ *
+ * .. impl:: Main Control Knob's main function
+ *    :id: SWIMPL_MCK-001
+ *    :implements: SWDD_MCK-001
+ * @endrst
+ */
 void mainControlKnob(void) {
     percentage_t currentValue = RteGetMainKnobValue();
     if (RteIsKeyPressed(CONTROL_KEY_UP)) {
-        // Increase brightness by 5 with a maximum of 100.
+        // Increase knob's percentage value by 5 with a maximum of 100.
         if (currentValue < (100 - KNOB_UPDATE_INCREMENT)) {
             currentValue += KNOB_UPDATE_INCREMENT;
         }
@@ -29,7 +29,7 @@ void mainControlKnob(void) {
         }
     }
     else if (RteIsKeyPressed(CONTROL_KEY_DOWN)) {
-        // Decrease brightness by 5 with a minimum of 0.
+        // Decrease knob's percentage value by 5 with a minimum of 0.
         if (currentValue > KNOB_UPDATE_INCREMENT) {
             currentValue -= KNOB_UPDATE_INCREMENT;
         }