[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/AnalogGyroSim.h

@@ -33,27 +33,82 @@ class AnalogGyroSim {
    */
   explicit AnalogGyroSim(int channel);
 
-  std::unique_ptr<CallbackStore> RegisterAngleCallback(NotifyCallback callback,
-                                                       bool initialNotify);
-
-  double GetAngle() const;
-
-  void SetAngle(double angle);
-
-  std::unique_ptr<CallbackStore> RegisterRateCallback(NotifyCallback callback,
-                                                      bool initialNotify);
-
-  double GetRate() const;
-
-  void SetRate(double rate);
-
-  std::unique_ptr<CallbackStore> RegisterInitializedCallback(
+  /**
+   * Register a callback on the angle.
+   *
+   * @param callback the callback that will be called whenever the angle changes
+   * @param initialNotify if true, the callback will be run on the initial value
+   * @return the CallbackStore object associated with this callback
+   */
+  [[nodiscard]] std::unique_ptr<CallbackStore> RegisterAngleCallback(
       NotifyCallback callback, bool initialNotify);
 
+  /**
+   * Get the current angle of the gyro.
+   *
+   * @return the angle measured by the gyro
+   */
+  double GetAngle() const;
+
+  /**
+   * Change the angle measured by the gyro.
+   *
+   * @param angle the new value
+   */
+  void SetAngle(double angle);
+
+  /**
+   * Register a callback on the rate.
+   *
+   * @param callback the callback that will be called whenever the rate changes
+   * @param initialNotify if true, the callback will be run on the initial value
+   * @return the CallbackStore object associated with this callback
+   */
+  [[nodiscard]] std::unique_ptr<CallbackStore> RegisterRateCallback(
+      NotifyCallback callback, bool initialNotify);
+
+  /**
+   * Get the rate of angle change on this gyro.
+   *
+   * @return the rate
+   */
+  double GetRate() const;
+
+  /**
+   * Change the rate of the gyro.
+   *
+   * @param rate the new rate
+   */
+  void SetRate(double rate);
+
+  /**
+   * Register a callback on whether the gyro is initialized.
+   *
+   * @param callback the callback that will be called whenever the gyro is
+   *                 initialized
+   * @param initialNotify if true, the callback will be run on the initial value
+   * @return the CallbackStore object associated with this callback
+   */
+  [[nodiscard]] std::unique_ptr<CallbackStore> RegisterInitializedCallback(
+      NotifyCallback callback, bool initialNotify);
+
+  /**
+   * Check if the gyro is initialized.
+   *
+   * @return true if initialized
+   */
   bool GetInitialized() const;
 
+  /**
+   * Set whether this gyro is initialized.
+   *
+   * @param initialized the new value
+   */
   void SetInitialized(bool initialized);
 
+  /**
+   * Reset all simulation data for this object.
+   */
   void ResetData();
 
  private: