docs: コメントを改善 (#257)

* update: mutex を利用しようとしていた時の名残コメントを削除した

* update: MdLed::coordinate の説明を改善した

* docs: コメントを改善

* docs: テストのコメントを改善

.vscode/settings.json

@@ -8,5 +8,8 @@
     "C_Cpp.default.cppStandard": "c++14",
     "C_Cpp.doxygen.generatedStyle": "/**",
     "C_Cpp.default.configurationProvider": "ms-vscode.cmake-tools",
-    "files.encoding": "utf8"
+    "files.encoding": "utf8",
+    "files.associations": {
+        "*.tcc": "cpp"
+    }
 }

src/spirit/include/MdLed.h

@@ -15,7 +15,7 @@ class MdLed {
 public:
     /**
      * @enum BlinkMode
-     * @brief LEDに設定する値のソースを何にするかの値
+     * @brief LEDの点滅種類を何にするかの値
      * @details 優先度は Error > Alternate = Concurrent l Normal
      */
     enum class BlinkMode {
@@ -71,10 +71,8 @@ class MdLed {
     void reset_error();
 
     /**
-     * @brief 時間を1単位進める
-     * @details Errorモードなどの場合、時間経過によってLEDの数値を変化させる
-     *
-     * 例えばblinking_rate(2)の時は、coordinate()を2回呼ぶごとにLEDの数値が変わる
+     * @brief 時間を1単位進め、時間経過によってLEDの数値を変化させる
+     * @details 例えばblinking_rate(2)の時は、coordinate()を2回呼ぶごとにLEDの数値が変わる
      */
     void coordinate();
 
@@ -92,10 +90,9 @@ class MdLed {
 
     Motor::State _state{Motor::Default::state};
     BlinkMode    _mode{Default::blink_mode};
-    // Mutex  _mutex;
-    uint32_t _interval{Default::interval};
-    uint32_t _counter{0};
-    uint32_t _error{0};
+    uint32_t     _interval{Default::interval};
+    uint32_t     _counter{0};
+    uint32_t     _error{0};
 
     uint32_t _error_section{0};
     uint32_t _error_bit_width{0};
@@ -108,7 +105,7 @@ class MdLed {
 
     /**
      * @brief LEDの点滅状態を返す
-     * @return LEDの点滅状態
+     * @return LEDの点滅状態(範囲: 0-3)
      */
     uint32_t read() const;
 

src/spirit/include/Motor.h

@@ -297,9 +297,9 @@ class Motor {
     static constexpr float min_pulse_period = 1.0F / 60000.0F;
     static constexpr float max_pulse_period = 1.0F / 10.0F;
 
-    /// デューティ比の変化具合の最小値 @n
-    /// Float 型の 1.00 に対してこれよりも小さい値を足しても、情報落ちして 1.00 より大きくならない
-    static constexpr float minimum_maximum_change_duty_cycle = 0.00000011920928955078125F;  // std::pow(2.0F, -23.0F)
+    /// デューティ比の変化具合の最小値(std::pow(2.0F, -23.0F)) @n
+    /// float 型の 1.00 に対してこれよりも小さい値を足しても、情報落ちして 1.00 より大きくならない
+    static constexpr float minimum_maximum_change_duty_cycle = 0.00000011920928955078125F;
 
 private:
     ControlSystem _control_system{Default::control_system};

tests/test_A3921.cpp

@@ -132,6 +132,12 @@ TEST(A3921, ResetTest)
  */
 TEST(A3921, SlowDecayLowSideTest)
 {
+    /**
+     * @brief テストの実体
+     * @param duty_cycle 設定するデューティー比
+     * @param expected_duty_cycle A3921から期待するデューティー比
+     * @param expected_status テスト終了後に期待する sprit::Error::Status
+     */
     auto test = [](float duty_cycle, float expected_duty_cycle, Error::Status expected_status) {
         Error& error = Error::get_instance();
         error.reset();
@@ -192,13 +198,14 @@ TEST(A3921, SlowDecayLowSideTest)
         }
     };
 
+    /// @test デューティー比が範囲内(0.00 < x < 1.00)の時に期待通りの出力になることを確認
     test(0.00F, 0.00F, Error::Status::Normal);
     test(0.01F, 0.01F, Error::Status::Normal);
     test(0.50F, 0.50F, Error::Status::Normal);
     test(0.99F, 0.99F, Error::Status::Normal);
     test(1.00F, 1.00F, Error::Status::Normal);
 
-    // デューティー比が範囲外(x < 0.00, 1.00 < x)のときに境界値になることを確認
+    /// @test デューティー比が範囲外(x < 0.00, 1.00 < x)のときに境界値になることを確認
     test(-0.01F, 0.00F, Error::Status::Warning);
     test(-1.00F, 0.00F, Error::Status::Warning);
     test(1.01F, 1.00F, Error::Status::Warning);
@@ -272,13 +279,14 @@ TEST(A3921, SlowDecayHighSideTest)
         }
     };
 
+    /// @test デューティー比が範囲内(0.00 < x < 1.00)の時に期待通りの出力になることを確認
     test(0.00F, 0.00F, Error::Status::Normal);
     test(0.01F, 0.01F, Error::Status::Normal);
     test(0.50F, 0.50F, Error::Status::Normal);
     test(0.99F, 0.99F, Error::Status::Normal);
     test(1.00F, 1.00F, Error::Status::Normal);
 
-    // デューティー比が範囲外(x < 0.00, 1.00 < x)のときに境界値になることを確認
+    /// @todo デューティー比が範囲外(x < 0.00, 1.00 < x)のときに境界値になることを確認
     test(-0.01F, 0.00F, Error::Status::Warning);
     test(-1.00F, 0.00F, Error::Status::Warning);
     test(1.01F, 1.00F, Error::Status::Warning);
@@ -291,15 +299,14 @@ TEST(A3921, SlowDecayHighSideTest)
  */
 TEST(A3921, MixedDecayTest)
 {
+    // 共通の設定
     StubDigitalOut sr;
     StubPwmOut     pwmh;
     StubPwmOut     pwml;
     StubPwmOut     phase;
     StubDigitalOut reset;
     A3921          a3921(sr, pwmh, pwml, phase, reset);
 
-    // 共通の設定
-
     // Error時に標準エラー出力に文字列が出力される
     // 本当のエラー時にエラー出力させたいので、異常系のテスト中は標準エラー出力をキャプチャする
     testing::internal::CaptureStderr();
@@ -388,6 +395,7 @@ TEST(A3921, FastDecayTest)
         }
     };
 
+    /// @test デューティー比が範囲内(0.00 < x < 1.00)の時に期待通りの出力になることを確認
     test(0.00F, 0.00F, Error::Status::Normal);
     test(0.01F, 0.01F, Error::Status::Normal);
     test(0.50F, 0.50F, Error::Status::Normal);