Moved C++ comments from source files to headers (#1111)

Also sorted functions in C++ sources to match order in related headers.

wpilibc/src/main/native/include/PWM.h

@@ -53,25 +53,170 @@ class PWM : public ErrorBase, public SendableBase {
     kPeriodMultiplier_4X = 4
   };
 
+  /**
+   * Allocate a PWM given a channel number.
+   *
+   * Checks channel value range and allocates the appropriate channel.
+   * The allocation is only done to help users ensure that they don't double
+   * assign channels.
+   *
+   * @param channel The PWM channel number. 0-9 are on-board, 10-19 are on the
+   *                MXP port
+   */
   explicit PWM(int channel);
+
+  /**
+   * Free the PWM channel.
+   *
+   * Free the resource associated with the PWM channel and set the value to 0.
+   */
   ~PWM() override;
+
+  /**
+   * Set the PWM value directly to the hardware.
+   *
+   * Write a raw value to a PWM channel.
+   *
+   * @param value Raw PWM value.
+   */
   virtual void SetRaw(uint16_t value);
+
+  /**
+   * Get the PWM value directly from the hardware.
+   *
+   * Read a raw value from a PWM channel.
+   *
+   * @return Raw PWM control value.
+   */
   virtual uint16_t GetRaw() const;
+
+  /**
+   * Set the PWM value based on a position.
+   *
+   * This is intended to be used by servos.
+   *
+   * @pre SetMaxPositivePwm() called.
+   * @pre SetMinNegativePwm() called.
+   *
+   * @param pos The position to set the servo between 0.0 and 1.0.
+   */
   virtual void SetPosition(double pos);
+
+  /**
+   * Get the PWM value in terms of a position.
+   *
+   * This is intended to be used by servos.
+   *
+   * @pre SetMaxPositivePwm() called.
+   * @pre SetMinNegativePwm() called.
+   *
+   * @return The position the servo is set to between 0.0 and 1.0.
+   */
   virtual double GetPosition() const;
+
+  /**
+   * Set the PWM value based on a speed.
+   *
+   * This is intended to be used by speed controllers.
+   *
+   * @pre SetMaxPositivePwm() called.
+   * @pre SetMinPositivePwm() called.
+   * @pre SetCenterPwm() called.
+   * @pre SetMaxNegativePwm() called.
+   * @pre SetMinNegativePwm() called.
+   *
+   * @param speed The speed to set the speed controller between -1.0 and 1.0.
+   */
   virtual void SetSpeed(double speed);
+
+  /**
+   * Get the PWM value in terms of speed.
+   *
+   * This is intended to be used by speed controllers.
+   *
+   * @pre SetMaxPositivePwm() called.
+   * @pre SetMinPositivePwm() called.
+   * @pre SetMaxNegativePwm() called.
+   * @pre SetMinNegativePwm() called.
+   *
+   * @return The most recently set speed between -1.0 and 1.0.
+   */
   virtual double GetSpeed() const;
+
+  /**
+   * Temporarily disables the PWM output. The next set call will reenable
+   * the output.
+   */
   virtual void SetDisabled();
+
+  /**
+   * Slow down the PWM signal for old devices.
+   *
+   * @param mult The period multiplier to apply to this channel
+   */
   void SetPeriodMultiplier(PeriodMultiplier mult);
+
   void SetZeroLatch();
+
+  /**
+   * Optionally eliminate the deadband from a speed controller.
+   *
+   * @param eliminateDeadband If true, set the motor curve on the Jaguar to
+   *                          eliminate the deadband in the middle of the range.
+   *                          Otherwise, keep the full range without modifying
+   *                          any values.
+   */
   void EnableDeadbandElimination(bool eliminateDeadband);
+
+  /**
+   * Set the bounds on the PWM pulse widths.
+   *
+   * This sets the bounds on the PWM values for a particular type of controller.
+   * The values determine the upper and lower speeds as well as the deadband
+   * bracket.
+   *
+   * @param max         The max PWM pulse width in ms
+   * @param deadbandMax The high end of the deadband range pulse width in ms
+   * @param center      The center (off) pulse width in ms
+   * @param deadbandMin The low end of the deadband pulse width in ms
+   * @param min         The minimum pulse width in ms
+   */
   void SetBounds(double max, double deadbandMax, double center,
                  double deadbandMin, double min);
+
+  /**
+   * Set the bounds on the PWM values.
+   *
+   * This sets the bounds on the PWM values for a particular each type of
+   * controller. The values determine the upper and lower speeds as well as the
+   * deadband bracket.
+   *
+   * @param max         The Minimum pwm value
+   * @param deadbandMax The high end of the deadband range
+   * @param center      The center speed (off)
+   * @param deadbandMin The low end of the deadband range
+   * @param min         The minimum pwm value
+   */
   void SetRawBounds(int max, int deadbandMax, int center, int deadbandMin,
                     int min);
+
+  /**
+   * Get the bounds on the PWM values.
+   *
+   * This Gets the bounds on the PWM values for a particular each type of
+   * controller. The values determine the upper and lower speeds as well as the
+   * deadband bracket.
+   *
+   * @param max         The Minimum pwm value
+   * @param deadbandMax The high end of the deadband range
+   * @param center      The center speed (off)
+   * @param deadbandMin The low end of the deadband range
+   * @param min         The minimum pwm value
+   */
   void GetRawBounds(int32_t* max, int32_t* deadbandMax, int32_t* center,
                     int32_t* deadbandMin, int32_t* min);
-  int GetChannel() const { return m_channel; }
+
+  int GetChannel() const;
 
  protected:
   void InitSendable(SendableBuilder& builder) override;