From da1e6e63ff179eb884ba0023369161df8ba83563 Mon Sep 17 00:00:00 2001
From: Vitaliy Sapronenko <vsapronenko@gmail.com>
Date: Thu, 23 May 2024 18:20:21 +0300
Subject: [PATCH] Mention of Vec normalization for Dir::new (#13483)

# Objective

- Fixes #13429 .

## Solution

- Improved docs for methods `new`, `new_and_length` of `Dir2`, `Dir3`,
`Dir3A`.
---
 crates/bevy_math/src/direction.rs | 15 +++++++++------
 1 file changed, 9 insertions(+), 6 deletions(-)

diff --git a/crates/bevy_math/src/direction.rs b/crates/bevy_math/src/direction.rs
index c51af927cfc06..5deeee2a835fd 100644
--- a/crates/bevy_math/src/direction.rs
+++ b/crates/bevy_math/src/direction.rs
@@ -95,7 +95,7 @@ impl Dir2 {
     /// The directional axes.
     pub const AXES: [Self; 2] = [Self::X, Self::Y];
 
-    /// Create a direction from a finite, nonzero [`Vec2`].
+    /// Create a direction from a finite, nonzero [`Vec2`], normalizing it.
     ///
     /// Returns [`Err(InvalidDirectionError)`](InvalidDirectionError) if the length
     /// of the given vector is zero (or very close to zero), infinite, or `NaN`.
@@ -118,7 +118,8 @@ impl Dir2 {
         Self(value)
     }
 
-    /// Create a direction from a finite, nonzero [`Vec2`], also returning its original length.
+    /// Create a direction from a finite, nonzero [`Vec2`], normalizing it and
+    /// also returning its original length.
     ///
     /// Returns [`Err(InvalidDirectionError)`](InvalidDirectionError) if the length
     /// of the given vector is zero (or very close to zero), infinite, or `NaN`.
@@ -288,7 +289,7 @@ impl Dir3 {
     /// The directional axes.
     pub const AXES: [Self; 3] = [Self::X, Self::Y, Self::Z];
 
-    /// Create a direction from a finite, nonzero [`Vec3`].
+    /// Create a direction from a finite, nonzero [`Vec3`], normalizing it.
     ///
     /// Returns [`Err(InvalidDirectionError)`](InvalidDirectionError) if the length
     /// of the given vector is zero (or very close to zero), infinite, or `NaN`.
@@ -311,7 +312,8 @@ impl Dir3 {
         Self(value)
     }
 
-    /// Create a direction from a finite, nonzero [`Vec3`], also returning its original length.
+    /// Create a direction from a finite, nonzero [`Vec3`], normalizing it and
+    /// also returning its original length.
     ///
     /// Returns [`Err(InvalidDirectionError)`](InvalidDirectionError) if the length
     /// of the given vector is zero (or very close to zero), infinite, or `NaN`.
@@ -488,7 +490,7 @@ impl Dir3A {
     /// The directional axes.
     pub const AXES: [Self; 3] = [Self::X, Self::Y, Self::Z];
 
-    /// Create a direction from a finite, nonzero [`Vec3A`].
+    /// Create a direction from a finite, nonzero [`Vec3A`], normalizing it.
     ///
     /// Returns [`Err(InvalidDirectionError)`](InvalidDirectionError) if the length
     /// of the given vector is zero (or very close to zero), infinite, or `NaN`.
@@ -511,7 +513,8 @@ impl Dir3A {
         Self(value)
     }
 
-    /// Create a direction from a finite, nonzero [`Vec3A`], also returning its original length.
+    /// Create a direction from a finite, nonzero [`Vec3A`], normalizing it and
+    /// also returning its original length.
     ///
     /// Returns [`Err(InvalidDirectionError)`](InvalidDirectionError) if the length
     /// of the given vector is zero (or very close to zero), infinite, or `NaN`.