From 2fc55b86a26cbaaf244c754567834583ee97e418 Mon Sep 17 00:00:00 2001
From: Gold856 <117957790+Gold856@users.noreply.github.com>
Date: Thu, 1 Aug 2024 19:41:57 -0400
Subject: [PATCH] [wpimath] Fix API docs for DCMotorSim and LinearSystemId
 (#6904)

---
 wpilibc/src/main/native/include/frc/simulation/DCMotorSim.h | 5 +++--
 .../java/edu/wpi/first/wpilibj/simulation/DCMotorSim.java   | 5 +++++
 .../edu/wpi/first/math/system/plant/LinearSystemId.java     | 6 +++---
 3 files changed, 11 insertions(+), 5 deletions(-)

diff --git a/wpilibc/src/main/native/include/frc/simulation/DCMotorSim.h b/wpilibc/src/main/native/include/frc/simulation/DCMotorSim.h
index c8019a36f9..f054596dcc 100644
--- a/wpilibc/src/main/native/include/frc/simulation/DCMotorSim.h
+++ b/wpilibc/src/main/native/include/frc/simulation/DCMotorSim.h
@@ -22,8 +22,9 @@ class DCMotorSim : public LinearSystemSim<2, 1, 2> {
    * Creates a simulated DC motor mechanism.
    *
    * @param plant              The linear system representing the DC motor. This
-   *                           system can be created with
-   *                           LinearSystemId::DCMotorSystem().
+   * system can be created with LinearSystemId::DCMotorSystem(). If
+   * LinearSystemId::DCMotorSystem(kV, kA) is used, the distance unit must be
+   * radians.
    * @param gearbox            The type of and number of motors in the DC motor
    * gearbox.
    * @param gearing            The gearing of the DC motor (numbers greater than
diff --git a/wpilibj/src/main/java/edu/wpi/first/wpilibj/simulation/DCMotorSim.java b/wpilibj/src/main/java/edu/wpi/first/wpilibj/simulation/DCMotorSim.java
index 0a86c11f68..169c288612 100644
--- a/wpilibj/src/main/java/edu/wpi/first/wpilibj/simulation/DCMotorSim.java
+++ b/wpilibj/src/main/java/edu/wpi/first/wpilibj/simulation/DCMotorSim.java
@@ -25,6 +25,11 @@ public class DCMotorSim extends LinearSystemSim<N2, N1, N2> {
    * Creates a simulated DC motor mechanism.
    *
    * @param plant The linear system representing the DC motor. This system can be created with
+   *     {@link edu.wpi.first.math.system.plant.LinearSystemId#createDCMotorSystem(DCMotor, double,
+   *     double)} or {@link
+   *     edu.wpi.first.math.system.plant.LinearSystemId#createDCMotorSystem(double, double)}. If
+   *     {@link edu.wpi.first.math.system.plant.LinearSystemId#createDCMotorSystem(double, double)}
+   *     is used, the distance unit must be radians.
    * @param gearbox The type of and number of motors in the DC motor gearbox.
    * @param gearing The gearing of the DC motor (numbers greater than 1 represent reductions).
    * @param measurementStdDevs The standard deviations of the measurements. Can be omitted if no
diff --git a/wpimath/src/main/java/edu/wpi/first/math/system/plant/LinearSystemId.java b/wpimath/src/main/java/edu/wpi/first/math/system/plant/LinearSystemId.java
index 761148a0f2..ac48939ef0 100644
--- a/wpimath/src/main/java/edu/wpi/first/math/system/plant/LinearSystemId.java
+++ b/wpimath/src/main/java/edu/wpi/first/math/system/plant/LinearSystemId.java
@@ -123,9 +123,9 @@ public final class LinearSystemId {
   }
 
   /**
-   * Create a state-space model of a DC motor system. The states of the system are [angular
-   * position, angular velocity], inputs are [voltage], and outputs are [angular position, angular
-   * velocity].
+   * Create a state-space model of a DC motor system from its kV (volts/(unit/sec)) and kA
+   * (volts/(unit/sec²)). These constants can be found using SysId. the states of the system are
+   * [position, velocity], inputs are [voltage], and outputs are [position].
    *
    * <p>The distance unit you choose MUST be an SI unit (i.e. meters or radians). You can use the
    * {@link edu.wpi.first.math.util.Units} class for converting between unit types.