[wpimath] Improve documentation for SwerveModulePosition::operator- (#5468)

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

@@ -76,7 +76,8 @@ public class SwerveModulePosition
   /**
    * Calculates the difference between two swerve module positions. The difference has a length
    * equal to the difference in lengths and an angle equal to the ending angle (this module
-   * position's angle).
+   * position's angle). This is suitable for representing a module's motion between two timesteps,
+   * because the final angle describes the direction the module moved.
    *
    * @param other The swerve module position to subtract.
    * @return The difference.

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

@@ -15,7 +15,7 @@ public interface WheelPositions<T extends WheelPositions<T>> extends Interpolata
   T copy();
 
   /**
-   * Returns the difference with another set of wheel positions.
+   * Returns a representation of how the wheels moved from other to this.
    *
    * @param other The other instance to compare to.
    * @return The representation of how the wheels moved from other to this.

wpimath/src/main/native/include/frc/kinematics/SwerveModulePosition.h

@@ -35,6 +35,16 @@ struct WPILIB_DLLEXPORT SwerveModulePosition {
    */
   bool operator==(const SwerveModulePosition& other) const;
 
+  /**
+   * Calculates the difference between two swerve module positions. The
+   * difference has a length equal to the difference in lengths and an angle
+   * equal to the ending angle (this module position's angle). This is suitable
+   * for representing a module's motion between two timesteps, because the final
+   * angle describes the direction the module moved.
+   *
+   * @param other The other swerve module position to subtract.
+   * @return The difference.
+   */
   SwerveModulePosition operator-(const SwerveModulePosition& other) const {
     return {distance - other.distance, angle};
   }