Documentation for DcMotor (#632)

* Docs, support failure detection

* typo

firmware/controllers/system/DcMotor.cpp

@@ -1,18 +1,21 @@
 /**
- *  @file	DcMotor.cpp
- *  @author Matthew Kennedy, (c) 2018
+ * @file DcMotor.cpp
+ * @brief DC motor controller
+ * 
+ * @date Dec 22, 2018
+ * @author Matthew Kennedy
  */
+
 #include "DcMotor.h"
 
 TwoPinDcMotor::TwoPinDcMotor(SimplePwm* pwm, OutputPin* dir1, OutputPin* dir2)
-    : m_dir1(dir1)
+    : m_pwm(pwm)
+    , m_dir1(dir1)
     , m_dir2(dir2)
-    , m_pwm(pwm)
 {
-
 }
 
-void TwoPinDcMotor::Set(float duty)
+bool TwoPinDcMotor::Set(float duty)
 {
     bool dir;
 
@@ -26,10 +29,10 @@ void TwoPinDcMotor::Set(float duty)
         dir = true;
     }
 
-    // Clamp
-    if(duty > 0.95f)
+    // Clamp to 100%
+    if(duty > 1.0f)
     {
-        duty = 0.95f;
+        duty = 1.0f;
     }
     // Disable for very small duty
     else if (duty < 0.01f)
@@ -49,4 +52,7 @@ void TwoPinDcMotor::Set(float duty)
     }
 
     m_pwm->setSimplePwmDutyCycle(duty);
+
+    // This motor has no fault detection, so always return false (indicate success).
+    return false;
 }

firmware/controllers/system/DcMotor.h

@@ -1,34 +1,53 @@
 /**
- *  @file	DcMotor.h
+ *  @file DcMotor.h
+ * 
+ *  @date Dec 22, 2018
  *  @author Matthew Kennedy, (c) 2018
  */
+
 #pragma once
 
 #include "pwm_generator_logic.h"
 
+/**
+ * @brief Brushed or brushless DC motor interface
+ * 
+ * Represents a DC motor (brushed or brushless) that provides simple
+ * torque/power/current/duty cycle control, but not accurate absolute position control.
+ */
 class DcMotor
 {
 public:
-/* unit tests rusefi_test.exe crashes with this, why?
-	virtual void Set(float duty) = 0;
-*/
+    /**
+     * @brief Sets the motor duty cycle.
+     * @param duty +1.0f represents full power forward, and -1.0f represents full power backward.
+     * @return True if any fault was detected driving the motor, and false if successful.
+     */
+    virtual bool Set(float duty) = 0;
 };
 
+/**
+ * @brief Represents a DC motor controller (H bridge) with one pin for enable (PWM),
+ * and two pins for direction control.
+ * 
+ * The enable pin is used for PWM and disable, and the two direction pins are used
+ * to set the polarity of each half of the H bridge.  setting {dir1,dir2} = 10 should,
+ * turn the motor one direction (positive duty), and = 01 should turn the other way (negative
+ * duty).
+ */
 class TwoPinDcMotor : public DcMotor
 {
 private:
+    SimplePwm* const m_pwm;
     OutputPin* const m_dir1;
     OutputPin* const m_dir2;
-    SimplePwm* const m_pwm;
 public:
+    /**
+     * @param pwm SimplePwm driver for enable pin, for PWM speed control.
+     * @param dir1 Enable 1 or direction 1 pin.  Gets set high to rotate forward.
+     * @param dir2 Enable 2 or direction 2 pin.  Gets set high to rotate backward.
+     */
     TwoPinDcMotor(SimplePwm* pwm, OutputPin* dir1, OutputPin* dir2);
 
-    /* unit tests rusefi_test.exe crashes with this, why?
-    virtual
-*/
-    void Set(float duty)
-    /* unit tests rusefi_test.exe crashes with this, why?
-     override
-*/
-     ;
+    virtual bool Set(float duty) override;
 };