[wpilib] Document simulation APIs (#3079)

- Remove sim checkstyle suppression
- Add [[nodiscard]] to C++ register callback functions
- Add a couple of missing sim functions

Co-authored-by: Peter Johnson <johnson.peter@gmail.com>
Co-authored-by: Starlight220 <yotamshlomi@gmail.com>

wpilibc/src/main/native/include/frc/simulation/PWMSim.h

@@ -33,48 +33,153 @@ class PWMSim {
    */
   explicit PWMSim(int channel);
 
-  std::unique_ptr<CallbackStore> RegisterInitializedCallback(
+  /**
+   * Register a callback to be run when the PWM is initialized.
+   *
+   * @param callback the callback
+   * @param initialNotify whether to run the callback with the initial state
+   * @return the CallbackStore object associated with this callback
+   */
+  [[nodiscard]] std::unique_ptr<CallbackStore> RegisterInitializedCallback(
       NotifyCallback callback, bool initialNotify);
 
+  /**
+   * Check whether the PWM has been initialized.
+   *
+   * @return true if initialized
+   */
   bool GetInitialized() const;
 
+  /**
+   * Define whether the PWM has been initialized.
+   *
+   * @param initialized whether this object is initialized
+   */
   void SetInitialized(bool initialized);
 
-  std::unique_ptr<CallbackStore> RegisterRawValueCallback(
+  /**
+   * Register a callback to be run when the PWM raw value changes.
+   *
+   * @param callback the callback
+   * @param initialNotify whether to run the callback with the initial value
+   * @return the CallbackStore object associated with this callback
+   */
+  [[nodiscard]] std::unique_ptr<CallbackStore> RegisterRawValueCallback(
       NotifyCallback callback, bool initialNotify);
 
+  /**
+   * Get the PWM raw value.
+   *
+   * @return the PWM raw value
+   */
   int GetRawValue() const;
 
+  /**
+   * Set the PWM raw value.
+   *
+   * @param rawValue the PWM raw value
+   */
   void SetRawValue(int rawValue);
 
-  std::unique_ptr<CallbackStore> RegisterSpeedCallback(NotifyCallback callback,
-                                                       bool initialNotify);
+  /**
+   * Register a callback to be run when the PWM speed changes.
+   *
+   * @param callback the callback
+   * @param initialNotify whether to run the callback with the initial value
+   * @return the CallbackStore object associated with this callback
+   */
+  [[nodiscard]] std::unique_ptr<CallbackStore> RegisterSpeedCallback(
+      NotifyCallback callback, bool initialNotify);
 
+  /**
+   * Get the PWM speed.
+   *
+   * @return the PWM speed (-1.0 to 1.0)
+   */
   double GetSpeed() const;
 
+  /**
+   * Set the PWM speed.
+   *
+   * @param speed the PWM speed (-1.0 to 1.0)
+   */
   void SetSpeed(double speed);
 
-  std::unique_ptr<CallbackStore> RegisterPositionCallback(
+  /**
+   * Register a callback to be run when the PWM position changes.
+   *
+   * @param callback the callback
+   * @param initialNotify whether to run the callback with the initial value
+   * @return the CallbackStore object associated with this callback
+   */
+  [[nodiscard]] std::unique_ptr<CallbackStore> RegisterPositionCallback(
       NotifyCallback callback, bool initialNotify);
 
+  /**
+   * Get the PWM position.
+   *
+   * @return the PWM position (0.0 to 1.0)
+   */
   double GetPosition() const;
 
+  /**
+   * Set the PWM position.
+   *
+   * @param position the PWM position (0.0 to 1.0)
+   */
   void SetPosition(double position);
 
-  std::unique_ptr<CallbackStore> RegisterPeriodScaleCallback(
+  /**
+   * Register a callback to be run when the PWM period scale changes.
+   *
+   * @param callback the callback
+   * @param initialNotify whether to run the callback with the initial value
+   * @return the CallbackStore object associated with this callback
+   */
+  [[nodiscard]] std::unique_ptr<CallbackStore> RegisterPeriodScaleCallback(
       NotifyCallback callback, bool initialNotify);
 
+  /**
+   * Get the PWM period scale.
+   *
+   * @return the PWM period scale
+   */
   int GetPeriodScale() const;
 
+  /**
+   * Set the PWM period scale.
+   *
+   * @param periodScale the PWM period scale
+   */
   void SetPeriodScale(int periodScale);
 
-  std::unique_ptr<CallbackStore> RegisterZeroLatchCallback(
+  /**
+   * Register a callback to be run when the PWM zero latch state changes.
+   *
+   * @param callback the callback
+   * @param initialNotify whether to run the callback with the initial state
+   * @return the CallbackStore object associated with this callback
+   */
+  [[nodiscard]] std::unique_ptr<CallbackStore> RegisterZeroLatchCallback(
       NotifyCallback callback, bool initialNotify);
 
+  /**
+   * Check whether the PWM is zero latched.
+   *
+   * @return true if zero latched
+   */
   bool GetZeroLatch() const;
 
+  /**
+   * Define whether the PWM has been zero latched.
+   *
+   * @param zeroLatch true to indicate zero latched
+   */
   void SetZeroLatch(bool zeroLatch);
 
+  /**
+   * Reset all simulation data.
+   */
   void ResetData();
 
  private: