[wpimath] Document drift from desaturating discretized chassis speeds (NFC) (#7741)

wpimath/src/main/java/edu/wpi/first/math/kinematics/ChassisSpeeds.java

@@ -96,7 +96,10 @@ public class ChassisSpeeds implements ProtobufSerializable, StructSerializable {
    * along the y-axis, and omega * dt around the z-axis).
    *
    * <p>This is useful for compensating for translational skew when translating and rotating a
-   * swerve drivetrain.
+   * holonomic (swerve or mecanum) drivetrain. However, scaling down the ChassisSpeeds after
+   * discretizing (e.g., when desaturating swerve module speeds) rotates the direction of net motion
+   * in the opposite direction of rotational velocity, introducing a different translational skew
+   * which is not accounted for by discretization.
    *
    * @param vxMetersPerSecond Forward velocity.
    * @param vyMetersPerSecond Sideways velocity.
@@ -134,7 +137,10 @@ public class ChassisSpeeds implements ProtobufSerializable, StructSerializable {
    * along the y-axis, and omega * dt around the z-axis).
    *
    * <p>This is useful for compensating for translational skew when translating and rotating a
-   * swerve drivetrain.
+   * holonomic (swerve or mecanum) drivetrain. However, scaling down the ChassisSpeeds after
+   * discretizing (e.g., when desaturating swerve module speeds) rotates the direction of net motion
+   * in the opposite direction of rotational velocity, introducing a different translational skew
+   * which is not accounted for by discretization.
    *
    * @param vx Forward velocity.
    * @param vy Sideways velocity.
@@ -157,7 +163,10 @@ public class ChassisSpeeds implements ProtobufSerializable, StructSerializable {
    * along the y-axis, and omega * dt around the z-axis).
    *
    * <p>This is useful for compensating for translational skew when translating and rotating a
-   * swerve drivetrain.
+   * holonomic (swerve or mecanum) drivetrain. However, scaling down the ChassisSpeeds after
+   * discretizing (e.g., when desaturating swerve module speeds) rotates the direction of net motion
+   * in the opposite direction of rotational velocity, introducing a different translational skew
+   * which is not accounted for by discretization.
    *
    * @param continuousSpeeds The continuous speeds.
    * @param dtSeconds The duration of the timestep the speeds should be applied for.

wpimath/src/main/java/edu/wpi/first/math/kinematics/SwerveDriveKinematics.java

@@ -274,6 +274,10 @@ public class SwerveDriveKinematics
    * reduce all the wheel speeds to make sure that all requested module speeds are at-or-below the
    * absolute threshold, while maintaining the ratio of speeds between modules.
    *
+   * <p>Scaling down the module speeds rotates the direction of net motion in the opposite direction
+   * of rotational velocity, which makes discretizing the chassis speeds inaccurate because the
+   * discretization did not account for this translational skew.
+   *
    * @param moduleStates Reference to array of module states. The array will be mutated with the
    *     normalized speeds!
    * @param attainableMaxSpeedMetersPerSecond The absolute max speed that a module can reach.
@@ -300,6 +304,10 @@ public class SwerveDriveKinematics
    * reduce all the wheel speeds to make sure that all requested module speeds are at-or-below the
    * absolute threshold, while maintaining the ratio of speeds between modules.
    *
+   * <p>Scaling down the module speeds rotates the direction of net motion in the opposite direction
+   * of rotational velocity, which makes discretizing the chassis speeds inaccurate because the
+   * discretization did not account for this translational skew.
+   *
    * @param moduleStates Reference to array of module states. The array will be mutated with the
    *     normalized speeds!
    * @param attainableMaxSpeed The absolute max speed that a module can reach.
@@ -318,6 +326,10 @@ public class SwerveDriveKinematics
    * reduce all the wheel speeds to make sure that all requested module speeds are at-or-below the
    * absolute threshold, while maintaining the ratio of speeds between modules.
    *
+   * <p>Scaling down the module speeds rotates the direction of net motion in the opposite direction
+   * of rotational velocity, which makes discretizing the chassis speeds inaccurate because the
+   * discretization did not account for this translational skew.
+   *
    * @param moduleStates Reference to array of module states. The array will be mutated with the
    *     normalized speeds!
    * @param desiredChassisSpeed The desired speed of the robot
@@ -365,6 +377,10 @@ public class SwerveDriveKinematics
    * reduce all the wheel speeds to make sure that all requested module speeds are at-or-below the
    * absolute threshold, while maintaining the ratio of speeds between modules.
    *
+   * <p>Scaling down the module speeds rotates the direction of net motion in the opposite direction
+   * of rotational velocity, which makes discretizing the chassis speeds inaccurate because the
+   * discretization did not account for this translational skew.
+   *
    * @param moduleStates Reference to array of module states. The array will be mutated with the
    *     normalized speeds!
    * @param desiredChassisSpeed The desired speed of the robot