From 488f64d7003feaca76b37331f0287b18fa53256b Mon Sep 17 00:00:00 2001
From: Daniel Beckwith <djbsnx@gmail.com>
Date: Mon, 9 Dec 2024 22:19:05 -0500
Subject: [PATCH] Fix atan2 docs (#16673)

# Objective

The parameter names for `bevy::math::ops::atan2` are labelled such that
`x` is the first argument and `y` is the second argument, but it passes
those arguments directly to
[`f32::atan2`](https://doc.rust-lang.org/stable/std/primitive.f32.html#method.atan2),
whose parameters are expected to be `(y, x)`. This PR changes the
parameter names in the bevy documentation to use the correct order for
the operation being performed. You can verify this by doing:

```rust
fn main() {
    let x = 3.0;
    let y = 4.0;
    let angle = bevy::math::ops::atan2(x, y);
    // standard polar coordinates formula
    dbg!(5.0 * angle.cos(), 5.0 * angle.sin());
}
```

This will print `(4.0, 3.0)`, which has flipped `x` and `y`. The problem
is that the `atan2` function to calculate the angle was really expecting
`(y, x)`, not `(x, y)`.

## Solution

I flipped the parameter names for `bevy::math::ops::atan2` and updated
the documentation. I also removed references to `self` and `other` from
the documentation which seemed to be copied from the `f32::atan2`
documentation.

## Testing

Not really needed, you can compare the `f32::atan2` docs to the
`bevy::math::ops::atan2` docs to see the problem is obvious. If a test
is required I could add a short one.
## Migration Guide

I'm not sure if this counts as a breaking change, since the
implementation clearly meant to use `f32::atan2` directly, so it was
really just the parameter names that were wrong.
---
 crates/bevy_math/src/ops.rs | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/crates/bevy_math/src/ops.rs b/crates/bevy_math/src/ops.rs
index 143f98ec0f..42fb55286c 100644
--- a/crates/bevy_math/src/ops.rs
+++ b/crates/bevy_math/src/ops.rs
@@ -143,7 +143,7 @@ mod std_ops {
         f32::atan(x)
     }
 
-    /// Computes the four quadrant arctangent of `self` (`y`) and `other` (`x`) in radians.
+    /// Computes the four-quadrant arctangent of `y` and `x` in radians.
     ///
     /// * `x = 0`, `y = 0`: `0`
     /// * `x >= 0`: `arctan(y/x)` -> `[-pi/2, pi/2]`
@@ -152,8 +152,8 @@ mod std_ops {
     ///
     /// Precision is specified when the `libm` feature is enabled.
     #[inline(always)]
-    pub fn atan2(x: f32, y: f32) -> f32 {
-        f32::atan2(x, y)
+    pub fn atan2(y: f32, x: f32) -> f32 {
+        f32::atan2(y, x)
     }
 
     /// Simultaneously computes the sine and cosine of the number, `x`. Returns
@@ -358,7 +358,7 @@ mod libm_ops {
         libm::atanf(x)
     }
 
-    /// Computes the four quadrant arctangent of `self` (`y`) and `other` (`x`) in radians.
+    /// Computes the four-quadrant arctangent of `y` and `x` in radians.
     ///
     /// * `x = 0`, `y = 0`: `0`
     /// * `x >= 0`: `arctan(y/x)` -> `[-pi/2, pi/2]`
@@ -367,8 +367,8 @@ mod libm_ops {
     ///
     /// Precision is specified when the `libm` feature is enabled.
     #[inline(always)]
-    pub fn atan2(x: f32, y: f32) -> f32 {
-        libm::atan2f(x, y)
+    pub fn atan2(y: f32, x: f32) -> f32 {
+        libm::atan2f(y, x)
     }
 
     /// Simultaneously computes the sine and cosine of the number, `x`. Returns