[wpimath] Better document trackwidth parameters (NFC) (#4324)

wpimath/src/main/java/edu/wpi/first/math/controller/LTVDifferentialDriveController.java

@@ -57,8 +57,9 @@ public class LTVDifferentialDriveController {
   /**
    * Constructs a linear time-varying differential drive controller.
    *
-   * @param plant The drivetrain velocity plant.
-   * @param trackwidth The drivetrain's trackwidth in meters.
+   * @param plant The differential drive velocity plant.
+   * @param trackwidth The distance between the differential drive's left and right wheels in
+   *     meters.
    * @param qelems The maximum desired error tolerance for each state.
    * @param relems The maximum desired control effort for each input.
    * @param dt Discretization timestep in seconds.

wpimath/src/main/java/edu/wpi/first/math/system/plant/LinearSystemId.java

@@ -271,11 +271,13 @@ public final class LinearSystemId {
   }
 
   /**
-   * Identify a standard differential drive drivetrain, given the drivetrain's kV and kA in both
-   * linear (volts/(meter/sec) and volts/(meter/sec²)) and angular (volts/(meter/sec) and
-   * volts/(meter/sec²)) cases. This can be found using SysId. The states of the system are [left
-   * velocity, right velocity]ᵀ, inputs are [left voltage, right voltage]ᵀ, and outputs are [left
-   * velocity, right velocity]ᵀ.
+   * Identify a differential drive drivetrain given the drivetrain's kV and kA in both linear
+   * (volts/(meter/sec) and volts/(meter/sec²)) and angular (volts/(radian/sec) and
+   * volts/(radian/sec²)) cases. This can be found using SysId.
+   *
+   * <p>States: [[left velocity], [right velocity]]<br>
+   * Inputs: [[left voltage], [right voltage]]<br>
+   * Outputs: [[left velocity], [right velocity]]
    *
    * @param kVLinear The linear velocity gain, volts per (meter per second).
    * @param kALinear The linear acceleration gain, volts per (meter per second squared).
@@ -315,17 +317,20 @@ public final class LinearSystemId {
   }
 
   /**
-   * Identify a standard differential drive drivetrain, given the drivetrain's kV and kA in both
-   * linear (volts/(meter/sec) and volts/(meter/sec²)) and angular (volts/(radian/sec) and
-   * volts/(radian/sec²)) cases. This can be found using SysId. The states of the system are [left
-   * velocity, right velocity]ᵀ, inputs are [left voltage, right voltage]ᵀ, and outputs are [left
-   * velocity, right velocity]ᵀ.
+   * Identify a differential drive drivetrain given the drivetrain's kV and kA in both linear
+   * (volts/(meter/sec) and volts/(meter/sec²)) and angular (volts/(radian/sec) and
+   * volts/(radian/sec²)) cases. This can be found using SysId.
+   *
+   * <p>States: [[left velocity], [right velocity]]<br>
+   * Inputs: [[left voltage], [right voltage]]<br>
+   * Outputs: [[left velocity], [right velocity]]
    *
    * @param kVLinear The linear velocity gain, volts per (meter per second).
    * @param kALinear The linear acceleration gain, volts per (meter per second squared).
    * @param kVAngular The angular velocity gain, volts per (radians per second).
    * @param kAAngular The angular acceleration gain, volts per (radians per second squared).
-   * @param trackwidth The width of the drivetrain in meters.
+   * @param trackwidth The distance between the differential drive's left and right wheels in
+   *     meters.
    * @return A LinearSystem representing the given characterized constants.
    * @throws IllegalArgumentException if kVLinear &lt;= 0, kALinear &lt;= 0, kVAngular &lt;= 0,
    *     kAAngular &lt;= 0, or trackwidth &lt;= 0.

wpimath/src/main/native/include/frc/controller/LTVDifferentialDriveController.h

@@ -35,8 +35,9 @@ class WPILIB_DLLEXPORT LTVDifferentialDriveController {
   /**
    * Constructs a linear time-varying differential drive controller.
    *
-   * @param plant      The drivetrain velocity plant.
-   * @param trackwidth The drivetrain's trackwidth.
+   * @param plant      The differential drive velocity plant.
+   * @param trackwidth The distance between the differential drive's left and
+   *                   right wheels.
    * @param Qelems     The maximum desired error tolerance for each state.
    * @param Relems     The maximum desired control effort for each input.
    * @param dt         Discretization timestep.

wpimath/src/main/native/include/frc/system/plant/LinearSystemId.h

@@ -183,11 +183,13 @@ class WPILIB_DLLEXPORT LinearSystemId {
   }
 
   /**
-   * Constructs the state-space model for a 2 DOF drivetrain velocity system
-   * from system identification data.
+   * Identify a differential drive drivetrain given the drivetrain's kV and kA
+   * in both linear (volts/(meter/sec) and volts/(meter/sec²)) and angular
+   * (volts/(radian/sec) and volts/(radian/sec²)) cases. This can be found using
+   * SysId.
    *
-   * States: [[left velocity], [right velocity]]
-   * Inputs: [[left voltage], [right voltage]]
+   * States: [[left velocity], [right velocity]]<br>
+   * Inputs: [[left voltage], [right voltage]]<br>
    * Outputs: [[left velocity], [right velocity]]
    *
    * @param kVlinear  The linear velocity gain in volts per (meter per second).
@@ -231,11 +233,13 @@ class WPILIB_DLLEXPORT LinearSystemId {
   }
 
   /**
-   * Constructs the state-space model for a 2 DOF drivetrain velocity system
-   * from system identification data.
+   * Identify a differential drive drivetrain given the drivetrain's kV and kA
+   * in both linear (volts/(meter/sec) and volts/(meter/sec²)) and angular
+   * (volts/(radian/sec) and volts/(radian/sec²)) cases. This can be found using
+   * SysId.
    *
-   * States: [[left velocity], [right velocity]]
-   * Inputs: [[left voltage], [right voltage]]
+   * States: [[left velocity], [right velocity]]<br>
+   * Inputs: [[left voltage], [right voltage]]<br>
    * Outputs: [[left velocity], [right velocity]]
    *
    * @param kVlinear   The linear velocity gain in volts per (meter per second).
@@ -245,7 +249,8 @@ class WPILIB_DLLEXPORT LinearSystemId {
    *                   second).
    * @param kAangular  The angular acceleration gain in volts per (radian per
    *                   second squared).
-   * @param trackwidth The width of the drivetrain.
+   * @param trackwidth The distance between the differential drive's left and
+   *                   right wheels.
    * @throws domain_error if kVlinear <= 0, kAlinear <= 0, kVangular <= 0,
    *         kAangular <= 0, or trackwidth <= 0.
    */