From e48f9d8cd4562d5ea6b483764ae9288feb13cc72 Mon Sep 17 00:00:00 2001
From: Rostyslav Toch <RokaRostuk@gmail.com>
Date: Sat, 18 Dec 2021 20:00:18 +0000
Subject: [PATCH] Add documentation and tests to AxisSettings (#3303)

# Objective

Fixes: #3247

## Solution

- Added short documentation for `AxisSettings`
- Added tests for `AxisSettings` and `ButtonSettings`


Co-authored-by: CrazyRoka <rokarostuk@gmail.com>
---
 crates/bevy_input/src/gamepad.rs | 130 ++++++++++++++++++++++++++++++-
 1 file changed, 129 insertions(+), 1 deletion(-)

diff --git a/crates/bevy_input/src/gamepad.rs b/crates/bevy_input/src/gamepad.rs
index 3b757c90cdfc0..a44a8a4cebc1c 100644
--- a/crates/bevy_input/src/gamepad.rs
+++ b/crates/bevy_input/src/gamepad.rs
@@ -154,12 +154,21 @@ impl ButtonSettings {
     }
 }
 
+/// Defines the sensitivity range and threshold for an axis.
+///
+/// Values that are lower than `negative_high` will be rounded to -1.0.
+/// Values that are higher than `positive_high` will be rounded to 1.0.
+/// Values that are in-between `negative_low` and `positive_low` will be rounded to 0.0.
+/// Otherwise, values will not be rounded.
+///
+/// The valid range is from -1.0 to 1.0, inclusive.
 #[derive(Debug, Clone)]
 pub struct AxisSettings {
     pub positive_high: f32,
     pub positive_low: f32,
     pub negative_high: f32,
     pub negative_low: f32,
+    ///`threshold` defines the minimum difference between old and new values to apply the changes.
     pub threshold: f32,
 }
 
@@ -364,7 +373,7 @@ const ALL_AXIS_TYPES: [GamepadAxisType; 8] = [
 
 #[cfg(test)]
 mod tests {
-    use super::ButtonAxisSettings;
+    use super::{AxisSettings, ButtonAxisSettings, ButtonSettings};
 
     fn test_button_axis_settings_filter(
         settings: ButtonAxisSettings,
@@ -421,4 +430,123 @@ mod tests {
             test_button_axis_settings_filter(settings, new_value, old_value, expected);
         }
     }
+
+    fn test_axis_settings_filter(
+        settings: AxisSettings,
+        new_value: f32,
+        old_value: Option<f32>,
+        expected: Option<f32>,
+    ) {
+        let actual = settings.filter(new_value, old_value);
+        assert_eq!(
+            expected, actual,
+            "Testing filtering for {:?} with new_value = {:?}, old_value = {:?}",
+            settings, new_value, old_value
+        );
+    }
+
+    #[test]
+    fn test_axis_settings_default_filter() {
+        let cases = [
+            (1.0, Some(1.0)),
+            (0.99, Some(1.0)),
+            (0.96, Some(1.0)),
+            (0.95, Some(1.0)),
+            (0.9499, Some(0.9499)),
+            (0.84, Some(0.84)),
+            (0.43, Some(0.43)),
+            (0.05001, Some(0.05001)),
+            (0.05, Some(0.0)),
+            (0.04, Some(0.0)),
+            (0.01, Some(0.0)),
+            (0.0, Some(0.0)),
+            (-1.0, Some(-1.0)),
+            (-0.99, Some(-1.0)),
+            (-0.96, Some(-1.0)),
+            (-0.95, Some(-1.0)),
+            (-0.9499, Some(-0.9499)),
+            (-0.84, Some(-0.84)),
+            (-0.43, Some(-0.43)),
+            (-0.05001, Some(-0.05001)),
+            (-0.05, Some(0.0)),
+            (-0.04, Some(0.0)),
+            (-0.01, Some(0.0)),
+        ];
+
+        for (new_value, expected) in cases {
+            let settings = AxisSettings::default();
+            test_axis_settings_filter(settings, new_value, None, expected);
+        }
+    }
+
+    #[test]
+    fn test_axis_settings_default_filter_with_old_values() {
+        let cases = [
+            (0.43, Some(0.44001), Some(0.43)),
+            (0.43, Some(0.44), None),
+            (0.43, Some(0.43), None),
+            (0.43, Some(0.41999), Some(0.43)),
+            (0.43, Some(0.17), Some(0.43)),
+            (0.43, Some(0.84), Some(0.43)),
+            (0.05, Some(0.055), Some(0.0)),
+            (0.95, Some(0.945), Some(1.0)),
+            (-0.43, Some(-0.44001), Some(-0.43)),
+            (-0.43, Some(-0.44), None),
+            (-0.43, Some(-0.43), None),
+            (-0.43, Some(-0.41999), Some(-0.43)),
+            (-0.43, Some(-0.17), Some(-0.43)),
+            (-0.43, Some(-0.84), Some(-0.43)),
+            (-0.05, Some(-0.055), Some(0.0)),
+            (-0.95, Some(-0.945), Some(-1.0)),
+        ];
+
+        for (new_value, old_value, expected) in cases {
+            let settings = AxisSettings::default();
+            test_axis_settings_filter(settings, new_value, old_value, expected);
+        }
+    }
+
+    #[test]
+    fn test_button_settings_default_is_pressed() {
+        let cases = [
+            (1.0, true),
+            (0.95, true),
+            (0.9, true),
+            (0.8, true),
+            (0.75, true),
+            (0.7, false),
+            (0.65, false),
+            (0.5, false),
+            (0.0, false),
+        ];
+
+        for (value, expected) in cases {
+            let settings = ButtonSettings::default();
+            let actual = settings.is_pressed(value);
+
+            assert_eq!(expected, actual, "Testing is pressed for value: {}", value);
+        }
+    }
+
+    #[test]
+    fn test_button_settings_default_is_released() {
+        let cases = [
+            (1.0, false),
+            (0.95, false),
+            (0.9, false),
+            (0.8, false),
+            (0.75, false),
+            (0.7, false),
+            (0.65, true),
+            (0.5, true),
+            (0.0, true),
+        ];
+
+        for (value, expected) in cases {
+            let settings = ButtonSettings::default();
+            let actual = settings.is_released(value);
+
+            assert_eq!(expected, actual, "Testing is released for value: {}", value);
+        }
+    }
 }